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libuv 中 文教 程 


翻译 自 《An Introduction to libuvò . 
会 持续 关注 原 教 程 并 更 新 中 文 版 ， 本 教程 基于 libuv 的 v1.3.0。 
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翻译 人 员 


e byronhe 
e littleneko 
e luohaha 


辅助 阅读 


1. libuv 官 方 文档 一 由 于 教程 有 些 知 识 点 讲解 得 不 够 深入 ， 需 要 我 们 自行 阅读 官方 
文档 ， 来 加 强 理解 。 

2. 教程 的 完整 代码 一 教程 中 展示 的 代码 并 不 完整 ， 对 于 一 些 复杂 的 程序 ， 需 要 阅 
读 完整 的 实例 代码 。 


说 明 


在 翻译 的 过 程 中 ， 对 于 一 些 个 人 觉得 可 能 不 是 那么 容易 理解 的 知识 点 ， 我 都 会 附 上 
自己 收集 的 说 明 资料 的 链接 ， 以 方便 学 习 。 由 于 个 人 的 英文 水 平 有 限 ， 如 果 大 家 发 


现 翻译 出 错 或 者 不 合适 的 地 方 ， 欢 迎 PR (修改 master 分 支 下 ，source 文 件 夹 下 的 
md 文件 即 可 ) 。 


Introduction 


本 书 由 很 多 的 libuv 教 程 组 成 ，libuv 是 一 个 高 性 能 的 ， 事 件 驱 动 的 |/O 库 ， 并 且 提 供 
了 跨 平台 (如 windows, linux) 的 API ° 

本 书 会 涵盖 libuv 的 主要 部 分 ， 但 是 不 会 详细 地 讲解 每 一 个 函数 和 数据 结构 。 官 方 文 
档 中 可 以 查阅 到 完整 的 内 容 。 


本 书 依然 在 不 断 完善 中 ， 所 以 有 些 章节 会 不 完整 ， 但 我 希望 你 能 喜欢 它 。 


Who this book is for 


如 果 你 正在 读 此 书 ， 你 或 许 是 : 


1. 系统 程序 员 ， 会 编写 一 些 底层 的 程序 ， 例 如 守护 进程 或 者 网 络 服务 器 E 
户 端 。 你 也 许 发 现 了 event-loop 很 适合 于 你 的 应 用 场景 ， 然 后 你 决定 使 用 
libuv ° 

2. 一 个 node.js 的 模块 开发 人 员 ， 决 定 使 用 C/C++ 封 装 系统 平台 某 些 同步 或 者 
异步 API， 并 将 其 暴露 给 Javascript。 你 可 以 在 node.js 中 只 使 用 libuv。 但 你 

1 需要 参考 其 他 资源 ， 因 为 本 书 并 没有 包括 v8/node.js 相 关 的 内 容 。 


本 书 假设 你 对 Cc 语言 有 一 定 的 了 解 。 


Background 


node.js 最 初 开 始 于 2009 年 ， 是 一 个 可 以 让 Javascript 代 码 离 开 浏 览 器 的 执行 环境 也 
可 以 执行 的 项 目 。node.js 使 用 了 Google 的 V8 解析 引擎 和 Marc Lehmann 的 libev ° 
Node.js 将 事件 驱动 的 |/O 模 型 与 适合 该 模型 的 编程 语言 (Javascript) 融 合 在 了 一 起 。 
随 着 node.js 的 日 益 流行 ，node.js 需 要 同时 支持 windows, 但 是 libev 只 能 在 Unix 环 境 
下 运行 。Windows 平台 上 与 kqueue(FreeBSD) 或 者 (e)poll(Linux) 等 内 核 事 件 通 知 相 
应 的 机 制 是 |OCP。libuv 提 供 了 一 个 跨 平台 的 抽象 ， 由 平台 决定 使 用 libev 或 IOCP ° 
在 node-v0.9.0 版 本 中 ，libuv 移 除了 libev 的 内 容 。 


随 着 libuv 的 日 益 成 熟 ， 它 成 为 了 拥有 车 越 性 能 的 系统 编程 库 。 除 了 node.js 以 外 ， 包 
括 Mozilla 的 Rust 编 程 语言 ， 和 许多 的 语言 都 开始 使 用 libuv。 


本 书 基于 libuv 的 v1.3.0。 


Code 


本 书 中 的 实例 代码 都 可 以 在 Github 上 找到 。 


Basics of libuv 


libuv 强 制 使 用 异步 的 ， 事 件 驱 动 的 编程 风格 。 它 的 核心 工作 是 提供 一 个 event- 
E a 
定时 器 ， 非 阻塞 的 网 络 支 持 ， 异 步 文 件 系统 访问 ， 子 进程 等 。 


Event loops 


在 事件 驱动 编程 中 ， 程 序 会 关注 每 一 个 事件 ， 并 且 对 每 一 个 事件 的 发 生 做 出 反应 。 
libuv 会 负责 将 来 自 操作 系统 的 事件 收集 起 来 ， 或 者 监视 其 他 来 源 的 事件 。 这 样 ， 用 
户 就 可 以 注册 回调 函数 ， 回 调 函 数 会 在 事件 发 生 的 时 候 被 调用 。event-loop 会 一 直 
保持 运行 状态 。 用 伪 代 码 描述 如 下 : 


while there are still events to process: 
= get the next event 
if there is a callback associated with e: 
call the callback 


举 几 个 事件 的 例子 : 


° Er 
e 包含 准备 被 读 取 的 数据 的 Socket ° 
° Sc 的 定时 器 。 


event-loop 最 终 会 被 uv_run() 启动 一 当 使 用 libuv 时 ， 最 后 都 会 调用 的 函数 。 


系统 编程 中 最 经 常 处 理 的 一 般 是 输入 和 输出 ， 而 不 是 一 大 堆 的 数据 处 理 。 问 题 在 于 
传统 的 输入 输出 函数 (例如 read > fprintf ) 都 是 阻塞 式 的 。 实 际 上 ， 向 文件 
写 入 数据 ， 从 网 络 读 取 数 据 所 花 的 时 间 ， 对 比 cpu 的 处 理 速 度 差 得 太 多 。 任 务 没 有 
完成 ， 函 数 是 不 会 返回 的 ， 所 以 你 的 程序 在 这 段 时 间 内 什么 也 做 不 了 。 对 于 需要 高 
性 能 的 的 程序 来 说 ， 这 是 一 个 主要 的 障碍 。 


a 是 使 用 多 线程 。 每 一 个 阻塞 的 /DO 操作 都 会 被 分 配 到 各 个 线 
程 中 (或 者 是 使 用 线程 池 ) 。 当 某 个 线程 一 旦 阻塞 ， 处 理 器 就 可 以 调度 处 理 其 他 需 
要 cpu 资 源 的 线程 。 


但 是 libuv 使 用 了 另外 一 个 解决 方案 ， 那 就 是 异步 ， 非 阻塞 。 大 多 数 的 现代 操作 系统 
GE 例如 ， 一 个 正常 的 Socket 上 的 read 调用 会 发 生 阻 

， 直 到 发 送 方 把 信息 发 送 过 来 。 但 是 ， 实 际 上 程序 可 以 请 求 操作 系统 监视 socket 
Seat, 并 将 这 个 事件 通知 放 到 事件 队列 中 。 这 样 ， 程 序 就 可 以 很 简单 地 检查 
事件 是 否 到 来 (可 能 此 时 正在 使 用 cpu 做 数值 处 理 的 运算 ) ， 并 及 时 地 获取 数据 。 
说 libuv 是 异步 的 ， 是 因为 程序 可 以 在 一 头 表 达 对 某 一 事件 的 兴趣 ， 并 在 另 一 头 获 取 
到 数据 (对 于 时 间或 是 空间 来 说 ) 。 它 是 非 阻塞 是 因为 应 用 程序 无 需 在 请 求 数据 后 


等 待 ， 可 以 自由 地 做 其 他 的 事 。libuv 的 事件 循环 方式 很 好 地 与 该 模型 匹配 , 因为 操 
作 系 统 事件 可 以 视 为 另外 一 种 libuv 事 件 . 非 阻塞 方式 可 以 保证 在 其 他 事件 到 来 时 被 
尽快 处 理 (当然 还 要 考虑 硬件 的 能 力 ) ° 


Note 


我 们 不 需要 关心 |/O 在 后 台 是 如 何 工作 的 ， 但 是 由 于 我 们 的 计算 [机 硬件 的 工作 方 
式 ， 线 程 是 处 理 器 最 基本 的 执行 单元 ，libuv 和 操作 系统 通常 会 运行 后 台 / 工 作者 
线程 , 或 者 采用 非 阻塞 方式 来 轮流 执行 任务 。 


Bert Belder， 一 个 libuv 的 核心 开发 者 ， 通 过 一 个 短视 频 向 我 们 解释 了 libuv 的 架构 和 
它 的 后 台 工 作 方 式 。 如 果 你 之 前 没有 接触 过 类 似 libuv，libev， 这 个 视频 会 非常 有 
用 。 视 频 的 网 址 是 https://youtu.be/nGn60vDSxQ4 。 


包含 了 libuv 的 event-loop 的 更 多 详细 信息 的 文档 。 


HELLO WORLD 


让 我 们 开始 写 第 一 个 libuv 程 序 吧 | 它 什 么 都 没 做 ， 只 是 开启 了 一 个 loop， 然 后 很 快 
地 退出 了 。 


helloworld/main.c 


#include <stdio.h> 
#include <stdlib.h> 
#include <uv.h> 


int main() í 
uv_loop_t *loop = malloc(sizeof(uv_loop_t)); 
uv_loop_init(loop); 


printi (Now quitting: Nna); 
uv_run(loop, UV_RUN_DEFAULT); 


uv_loop_close(loop); 
free(loop); 
returno; 
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数 来 告诉 event-loop 我 们 要 监视 的 事件 。 


从 libuv 的 1.0 版 本 开始 ， 用 户 就 可 以 在 使 用 uv_loop_init 初始 化 loop 之 前 ， 给 其 
分 配 相应 的 内 存 。 这 就 允许 你 植 入 自 定义 的 内 存 管理 方法 。 记 住 要 使 

用 uv_loop_close(uv_loop_t *) 关闭 loop， 然 后 再 回收 内 存 空 间 。 在 例子 中 ， 
程序 退出 的 时 候 会 关闭 loop， 系 统 也 会 自动 回收 内 存 。 对 于 长 时 间 运 行 的 程序 来 
说 ， 合 理 释 放 内 存 很 重要 。 


Default loop 


可 以 使 用 uv_default_loop 获取 libuv 提 供 的 默认 loop。 如 果 你 只 需要 一 个 loop 的 
话 ， 可 以 使 用 这 个 。 
Note 


nodejs 中 使 用 了 默认 的 loop 作 为 自己 的 主 Ioop。 如 果 你 在 编写 nodejs 的 绑 定 ， 
你 应 该 注意 一 下 。 


Error handling 


初始 化 函数 或 者 是 同步 执行 的 函数 ， 会 在 执行 失败 后 返回 代表 错误 的 负数 。 但 是 对 
于 异步 执行 的 函数 ， 会 在 执行 失败 的 时 候 ， 给 它们 的 回调 函数 传递 一 个 状态 参数 。 
错误 信息 被 定义 为 WE 常量 。 


你 可 以 使 用 uv_strerror(int) 和 uv_err_name(int) 分 别 获 

取 const char * 格式 的 错误 信息 和 错误 名 字 。 

I/O 轴 数 的 回调 函数 (例如 文件 和 socket 等 ) 会 被 传递 一 个 nread 参数 。 如 

果 nread 小 于 0， 就 代表 出 现 了 错误 (当然 ，UV_EOF 是 读 取 到 文件 末端 的 错误 ， 
你 要 特殊 处 理 ) 。 


Handles and Requests 
libuv 的 工作 建立 在 用 户 表达 对 特定 事件 的 兴趣 。 这 通常 通过 创造 对 应 MO 设备 ， 定 时 


器 ， 进 程 等 的 handle 来 实现 。handle 是 不 透明 的 数据 结构 ， 其 中 对 应 的 类 
型 uv_TYPE t 中 的 type 指 定 了 handle 的 使 用 目的 。 


libuv watchers 


/* Hand le types. */ 

typedef struct uv_loop_s uv_loop_t; 
typedef struct uv_handle_s uv_handle_t; 
typedef struct uv_stream_s uv_stream_t; 
typedef struct uv tcp s UV tep t; 

typedef struct uv_udp_s uv_udp_t; 

typedef struct uv_pipe_s uv_pipe_t; 
typedef struct uv_tty_s uv_tty_t; 

typedef struct uv_poll_s uv_poll_t; 
typedef struct uv_timer_s uv_timer_t; 
typedef struct uv_prepare_s uv_prepare_t; 
typedef struct uv_check_s uv_check_t; 
typedef struct uv_idle s uv_idle t; 
typedef struct uv_async_s uv_async_t; 
typedef struct uv_process_s uv_process_t; 
typedef struct uv_fs_event_s uv_fs_event_t; 
typedef struct uv_fs_poll_s uv_fs_poll_t; 
typedef struct uv_signal_s uv_signal t; 



































/* Request types. */ 

typedef struct uv_req_s uv_req_t; 

typedef struct uv_getaddrinfo_s uv_getaddrinfo_t; 
typedef struct uv_getnameinfo_s uv_getnameinfo_t; 
typedef struct uv_shutdown_s uv_shutdown_t; 
typedef struct uv_write_s uv_write t; 

typedef struct uv_connect_s uv_connect_t; 

typedef struct uv_udp_send_s uv_udp_send_t; 
typedef struct uv fs s Uv fs t; 

typedef struct uv_work_s uv_work_t; 

















Z"None or the above a 

typedef struct uv_cpu_info_s uv_cpu_info_t; 

typedef struct uv_interface_address_s uv_interface_address_t; 
typedef struct uv_dirent_s uv_dirent_t; 





handle 代 表 了 持久 性 对 象 。 在 异 EE 相应 的 handle 上 有 许多 与 之 关联 的 

request。request 是 短暂 性 对 象 ( 通 常 只 维持 在 一 个 回调 函数 的 时 间 ) ， 通 常 对 映 

着 handle 上 的 一 个 |/O 操 作 。request 用 来 在 初始 函数 和 回调 函数 之 间 ， 传 递 上 下 

文 。 例 如 uv_udp_t 代 表 了 一 个 udp 的 socket， 然 而 ， 对 于 每 一 个 向 socket 的 写 入 的 
完成 后 ， 都 会 向 回调 函数 传递 一 个 uv_udp_send t ° 


handle 可 以 通过 下 面 的 函数 设置 : 


uv_TYPE_init(uv_loop_t *, uv_TYPE_t *) 


回调 函数 是 libuv 所 关注 的 事件 发 生 后 ， 所 调用 的 函数 。 应 用 程序 的 特定 逻辑 会 在 回 
调 函数 中 实现 。 例 如 ， 一 个 IO 监视 器 的 回调 函数 会 接收 到 从 文件 读 取 到 的 数据 ， 一 
个 定时 器 的 回调 有 陈 数 会 在 超时 后 被 触发 等 等 ° 


Idling 


下 面 有 一 个 使 用 空转 handle 的 例子 。 回 调 函 数 在 每 一 个 循环 中 都 会 被 调用 。 在 
Utilities 这 部 分 会 讲 到 一 些 空转 handle 的 使 用 场景 。 现 在 让 我 们 使 用 一 个 空转 监视 
器 ， 然 后 来 观察 它 的 生命 周期 ， 接 着 看 uv_run 调用 是 否 会 造成 阻塞 。 当 达到 事先 
规定 好 的 计数 后 ， 空 转 监视 器 会 退出 。 因 为 uv_run 已 经 找 不 到 活着 的 事件 监视 器 
T > PYA uv_run() 也 退出 。 


idle-basic/main.c 


#include <stdio.h> 
#include <uv.h> 


Int64 t counter = 0; 


void wait for_a while(uv_idle t* handle) í 


counter++; 


if (counter >= 10e6) 
uv_idle_stop(handle); 


} 

ne mem ed 
uv_idle t idler; 
uv_idle init(uv_default loop(), &idler); 
uv_idle start(&idler, wait Tor a while); 
pr int d Ge ino Nn E 
uv_run(uv_default_loop(), UV_RUN_DEFAULT); 
uv_loop_close(uv_default_loop()); 
return 0; 

} 


Storing context 


在 基于 回调 函数 的 编程 风格 中 ， 你 可 能 会 需要 在 调用 处 和 回调 函数 之 间 ， 传 递 一 些 
上 下 文 等 特定 的 应 用 信息 。 所 有 的 handle 和 request 都 有 一 个 data 域 ， 可 以 用 来 
存储 信息 并 传递 。 这 是 一 个 Cc 语言 库 中 很 常见 的 模式 。 即 使 是 uv_loop t 也 有 一 个 
相似 的 data 域 。 


Filesystem 


简单 的 文件 读 写 是 通过 uv _fs * 函数 族 和 与 之 相关 的 uv fs t 结构 体 完成 的 . 


note 


libuv 提供 的 文件 操作 和 socket operations 并 不 相同 . 套 接 字 操作 使 用 了 操作 系 
统 本 身 提供 了 非 阻塞 操作 , 而 文件 操作 内 部 使 用 了 阻塞 函数 , 但 是 libuv 是 在 线 
程 池 中 调用 这 些 函 数 ,并 在 应 用 程序 需要 交互 时 通知 在 事件 循环 中 注册 的 监视 
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所 有 的 文件 操作 函数 都 有 两 种 形式 - 同步 synchronous 和 SP asynchronous. 


同步 synchronous 形式 如 果 没 有 指定 回调 函数 则 会 被 自动 调用 ( 并 阻塞 的 ), 函数 的 
返回 值 是 libuv error code .但 以 上 通常 只 对 同步 调用 有 意义 


而 异步 asynchronous 形式 则 会 在 传 入 回调 函数 时 被 调用 , 并 且 返 回 0. 


Reading/Writing files 
文件 描述 符 可 以 采用 如 下 方式 获得 : 

Ime Uvis open(Uv roop Ee EEN UV fs t redr Consti echar pach Da 
二 雯 


参数 flags 与 mode 和 标准 的 Unix flags 相同 . libuv 会 小 心地 处 理 Windows 环境 
下 的 相关 标志 位 (flags) 的 转换 , 所 以 编写 跨 平台 程序 时 你 不 用 担心 不 同 平台 上 文件 打 
开 的 标志 位 不 同 。 


关闭 文件 描述 符 可 以 使 用 : 





Ime U Ces HOT loop df fe lee TV dh CH dl reg TVA ECG ACHT AA CH 
IER 
文件 系统 的 回调 函数 有 如 下 的 形式 : 





void callback(uv_fs t* req); 


让 我 们 看 一 下 一 个 简单 的 cat 命令 的 实现 。 我 们 通过 注册 一 个 当 文 件 被 打开 时 被 
调用 的 回调 函数 来 开始 : 


uvcat/main.c - opening a file 


// The request passed to the callback is the same as the one tl 
// function was passed. 
assert(req == &open_req); 
if (req->result >= 0) í 
iov = uv_buf_init(buffer, sizeof(buffer)); 
uv_fs_read(uv_default_loop(), &read_req, req->result, 
&iov, 1, -1, on_read); 
} 


else í 
fprintf(stderr, "error opening file: %sNn", uv_strerror((ir 





uv _fs_t 的 result 域 保存 了 uv fs open 回调 函数 打开 的 文件 描述 符 。 如 果 
文件 被 正确 地 打开 ， 我 们 可 以 开始 读 取 了 : 


void on_read(uv fs t *req) í 
if (req->result < 0) í 
fprintf(stderr, "Read error: %sNn", uv_strerror(req->resull 


else if (req->result == 0) í 
uv_fs_t close_req; 
// synchronous 


uv_fs_close(uv_default_loop(), &close_req, open_req.result, 


else if (req->result > 0) í 
iov.len = req->result; 
uv_fs_write(uv_default_loop(), &write_req, 1, &iov, 1, -1, 





在 调用 读 取 函 数 的 时 候 ， 你 必须 传递 一 个 已 经 初始 化 的 缓冲 区 ， 在 on read() 被 
触发 后 ， 缓 冲 区 被 被 写 入 数据 。 uv_fs_* 系列 的 函数 是 和 POSIX 的 函数 对 应 的 ， 
所 以 当 读 到 文件 的 末尾 时 (EOF)，result 返 回 0。 在 使 用 streams 或 者 pipe 的 情况 下 ， 
使 用 的 是 libuv 自 定义 的 UV EOF ° 


现在 你 看 到 类 似 的 异步 编程 的 模式 。 但 是 uv_fs_close() 是 同步 的 ， 一 般 来 说 ， 
一 次 性 的 ， 开 始 的 或 者 关闭 的 部 分 ， 都 是 同步 的 ， 因 为 我 们 一 般 关 心 的 主要 是 任务 
和 多 路 IJ/O 的 快速 MO 。 所 以 在 这 些 对 性 能 微不足道 的 地 方 ， 都 是 使 用 同步 的 ， 这 样 
代码 还 会 简单 一 些 。 


文件 系统 的 写 入 使 用 uv_fs write() ， 当 写 入 完成 时 会 触发 回调 函数 ， 在 这 个 例 
子 中 回调 函数 会 触发 下 一 次 的 读 取 。 


uvcat/main.c - write callback 


void on write(uv fs t *req) í 
if (req->result < 0) { 
fprintf(stderr, "Write error: %s\n", uv_strerror((int)req-: 








} 
else í 
uv_fs_read(uv_default_loop(), &read_req, open reg. result, é 
} 
} 
Warning 


由 于 文件 系统 和 磁盘 的 调度 策略 ， 写 入 成 功 的 数据 不 一 定 就 存在 磁盘 上 。 
我 们 开始 在 main 中 推动 多 米 诺 骨牌 : 


uvcat/main.c 


ee UE EK E arge ena arov E 
uv Te _ open(uv_default loop(), &open_ reg, argv[1], O_RDONLY, ©, 
Uv_run(uv_default loop(), UV_RUN_DEFAULT); 


uv_fs_req cleanup(&open reng): 
uv_fs_req cleanup(&read req); 
uv_fs_req cleanup(&write_ req); 
return 0; 


} 
到 == Š 





Warning 


函数 Uv_fs_req_cleanup() 在 文件 系统 操作 结束 后 必须 要 被 调用 ， 用 来 回收 在 读 
写 中 分 配 的 内 存 。 


Filesystem operations 


所 有 像 unlink , rmdir ，stat 这 样 的 标准 文件 操作 都 是 支持 异步 的 ， 并 且 使 
用 方法 和 上 述 类 似 。 下 面 的 各 个 函数 的 使 用 方法 和 read/write/open 类 似 ， 

在 uv fs t.result 中 保存 返回 值 .所 有 的 函数 如 下 所 示 : 

( 译 者 注 : 返回 的 result 值 ，<0 表 示 出 错 ， 其 他 值 表 示 成 功 。 但 >=0 的 值 在 不 同 的 区 
数 中 表示 的 意义 不 一 样 ， 比 如 在 uv_fs_read 或 者 uv_fs_write 中 ， 它 代表 读 取 
或 写 入 的 数据 总 量 ， 但 在 uv_fs_open 中 表示 打开 的 文件 描述 符 .) 


UV_EXTERN int uv Te close(uv_ 1Loop_t* loop, 
UV Te Ch reg, 
uv_file file, 
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UV fs cb cb); 
UV_EXTERN int uv_fs_open(uv_loop_t* loop, 
uv fs të reg, 
const char path, 
int flags, 
int mode, 
uvis cheb); 
UV_EXTERN int uv_fs_read(uv_loop_t* loop, 
UV Te Ch reg, 
uv_file file, 
const Th ec bufs, 
unsigned int nbufs, 
1ntG4 CC offser, 
Haer 
UV EXTERN nt uv Te unlinktiuv Loop rr Loop, 
uv Te tr reg, 
const char* path, 
UN 人 ESs 划 Cpceby 
UV_EXTERN int uv fs write(uv_ loop t* loop, 
UV Te Ch reg, 
UV file file, 
Const OB St pus nt 
unsigned int nbufs, 
int64 t offset, 
Heer 
UV EXTERN nt uv Te mkdir (UV JIoop rr Loop, 
UV Te t reg, 
const char* path, 
int mode, 
NF e Telo DR 
UV_EXTERN int uv_fs_mkdtemp(uv_loop_t* loop, 
Uv Te Ch reg, 
const char* tpl, 
UVES role) (elo): 
UV_EXTERN int uv_fs_rmdir(uv_loop_t* loop, 
uv fs t req, 
const char* path, 
UVIS Eo eoe 
UV EXTERN Int uv Te scandiriuv loopt Loop, 
HE reg, 
const char* path, 
Duke Tags; 
úvafs icb eb) 
UV_EXTERN int uv_fs_scandir_next(uv_fs_t* req, 
uv_dirent_t* ent); 
UV EXTERN Int uv Te statiuv Loop t Loop, 
uv Te Ch reg, 
const char* path, 
NEE CD) 
UV_EXTERN int uv Te fstat(uv_loop_t* loop, 
uv fs t req, 
uv_file file, 
HE 
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UV_EXTERN int uv_fs rename(uv_loop t* loop, 
uv Te tr reg, 
const ehar path, 
const char* new_path, 
uv fs cb cb); 

UV_EXTERN int uv_fs_fsync(uv_loop_t* loop, 

UV fs t* req, 
uv_file file, 
Serge 
UV_EXTERN int uv fs fdatasync(uv Loop t* loop, 
úv fs Ch reg, 
uv_file file, 
HN Te bs 
UV_EXTERN int uv_fs ftruncate(uv Loop t* loop, 
úv fs t reg, 
úv file file, 
int64_t offset, 
HE cb); 
UV_EXTERN int uv_fs sendfile(uv_ Loop t* Loop, 
UV ES (Ped; 
uv_file out fd, 
uv r re mn fg, 
int64 t in_offset, 
size t length, 
UV fs cb cb); 

UV_EXTERN int uv_fs_access(uv_loop_t* loop, 
us fs Li reg; 
const char* path, 
int mode, 

H eo) 
UV EXTERN nt uv Te chmodiuv loop t Loop, 
UV Te Ch reg, 
const char* path, 
int mode, 
üv fs cb cb); 
UV_EXTERN int uv_fs_utime(uv_loop_t* loop, 
uv Te Ch reg, 
const char* path, 
double atime, 
double mtime, 
UV fS Cb eD); 
UV_EXTERN int uv_fs_futime(uv_loop_t* loop, 
UV Te treg, 
uv_file file, 
double atime, 
double mtime, 
HE 
UN EXTERN nt uv Te Leratiuwv Loop Er Loop, 
UV Te t* reg, 
const char* path, 
VE in ep); 

UV ENXTERN nt uv Te Lunkiuv Loop GC Loop, 
He EE 
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Const Chart path, 
const Char" new_path, 
UVEfSs Co ech); 


Buffers and Streams 


在 libuv 中 ， 最 基础 的 |/O 操 作 是 流 stream( uv_stream t )。TCP 套 接 字 ，UDP 套 接 
字 ， 管 道 对 于 文件 MO 和 IPC 来 说 ， 都 可 以 看 成 是 流 stream( uv_stream t ) 的 子 类 . 
上 面 提 到 的 各 个 流 的 子 类 都 有 各 自 的 初始 化 函数 ， 然 后 可 以 使 用 下 面 的 也 数 操作 : 


int UV read start(uv stream t*, uv alloc cb alloc ch, uv read cb rt 
Dt uv read stop(uv stream EI: 
int úv_write(uv_write t* req, UN stream t* handle, 

conse uv DUF Chute), unsigoned nt nbufs, Uu WEI) 


HEEE 


可 以 看 出 ， 流 操作 要 比 上 述 的 文件 操作 要 简单 一 些 ， 而 且 当 uv_read_start() 一 
旦 被 调用 ，libuv 会 保持 从 流 中 持续 地 读 取 数 据 ， 直 到 uv read stop) 被 调用 。 

数据 的 离散 单元 是 buffer- uv butter t 。 它 包含 了 指向 数据 的 开始 地 址 的 指针 

( uv_buf_t.base ) 和 buffer 的 长 度 ( uv_buf t.len ) 这 两 个 信息 。 uv_buf_t 很 
轻 量 级 ， 使 用 值 传 递 。 我 们 需要 管理 的 只 是 实际 的 数据 ， 即 程序 必须 自己 分 配 和 回 
收 内 存 。 


.. ERROR:: 





THIS PROGRAM DOES NOT ALWAYS WORK, NEED SOMETHING BETTER** 


为 了 更 好 地 演示 流 stream， 我 们 将 会 使 用 uv _pipe t 。 它 可 以 将 本 地 文件 转换 为 
流 (stream) 的 形态 。 接 下 来 的 这 个 是 使 用 libuv 实 现 的 ， 一 个 简单 的 T 型 工具 (如 
果 不 是 很 了 解 ， 请 看 维基 百科 )) 。 所 有 的 操作 都 是 异步 的 ， 这 也 正 是 事件 驱动 |/O 
的 威力 所 在 。 两 个 输出 操作 不 会 相互 阻塞 ， 但 是 我 们 也 必须 要 注意 ， 确 保 一 块 缓冲 
区 不 会 在 还 没有 写 入 之 前 ， 就 提前 被 回收 了 。 


这 个 程序 执行 命令 如 下 
./uvtee <output_file> 
在 使 用 pipe 打 开 文件 时 ，libuv 会 默认 地 以 可 读 和 可 写 的 方式 打开 文件 。 


uvteelmain.c - read on pipes 


imt masin pie argc, Char Zargovl 人 
loop = uv_default_loop(); 


uv_pipe_init(loop, &stdin_pipe, 0); 
uv_pipe_open(&stdin_pipe, 0); 


uv_pipe_init(loop, &stdout_pipe, 0); 
uv_pipe_open(&stdout_pipe, 1); 


uv_fs_t file reg: 

int fd = uv_fs_open(loop, &file req, argv[1], O_ CREAT | O_RDWR, 
uv_pipe_init(loop, &file pipe, 0); 

uv_pipe_open(&file pipe, fd); 


uv_read_start((uv stream t*)&stdin_pipe, alloc_buffer, read st 


uv_run(loop, UV RUN DEFAULT); 
return o; 


DI 


当 需 要 使 用 IPC 的 命名 管道 的 时 候 (无 名 管道 是 Unix 最 初 的 /PC 形式 ， 但 是 由 于 无 名 
管道 的 局 限 性 ， 后 来 出 现 了 有 名 管道 FIFO， 这 种 管道 由 于 可 以 在 文件 系统 中 创建 一 
个 名 字 ， 所 以 可 以 被 没有 亲缘 关系 的 进程 访问 ) ° uv_pipe init() 的 第 三 个 参 
数 应 该 被 设置 为 1。 这 部 分 会 在 Process 进 程 的 这 一 章节 说 

B] ° uv_pipe_open() 函数 把 管道 和 文件 描述 符 关 联 起 来 ， 在 上 面 的 代码 中 表示 
把 管道 stdin_pipe 和 标准 输入 关联 起 来 〈( 译 者 注 : 0 代表 标准 输入 ， 1 代表 
标准 输出 ， 2 代表 标准 错误 输出 ) ° 


当 调 用 uv_read_start() 后 ， 我 们 开始 监听 stdin ， 当 需要 新 的 缓冲 区 来 存储 
数据 时 ， 调 用 alloc_buffer， 在 函数 read_stdin() 中 可 以 定义 缓冲 区 中 的 数据 处 
理 操作 ° 





uvtee/main.c - reading buffers 


void alloc buffer(uv handle t “handle, size t suggested size, uv D 
*buf = uv_buf_init((char*) malloc(suggested_size), suggested s: 
} 


void read stdin(uv_stream t *stream, ssize t nread, const uv_buf t 
if (nread < 0){ 
if (nread == UN EOEN 
// end of file 
uv_close((uv_handle_t *)&stdin pipe, NULL); 
uv_close((uv_handle_t *)&stdout pipe, NULL); 
Uv_close((uv_handle t *)&file pipe, NULL); 


} 

y else if (nread > 0) í 
write _data((uv stream t *)&stdout_pipe, nread, *buf, on St 
write _data((uv stream t *)&file pipe, nread, *buf, on file 


} 


if (buf->base) 
free(buf->base); 





标准 的 malloc 是 非常 高 效 的 方法 ， 但 是 你 依然 可 以 使 用 其 它 的 内 存 分 配 的 策略 。 
比如 ，nodejs 使 用 自己 的 内 存 分 配方 法 〈 Smalloc ) ， 它 将 buffer 用 v8 的 对 象 关 联 
起 来 ， 具 体 的 可 以 查看 hodejs 的 官方 文档 。 


当 回 调 函 数 read_stdin() 的 nread 参 数 小 于 0 时 ， 表 示 错 误 发 生 了 。 其 中 一 种 可 
能 的 错误 是 EOF( 读 到 文件 的 尾部 )， 这 时 我 们 可 以 使 用 函数 uv_close() 关闭 流 
了 。 除 此 之 外 ， 当 nread 大 于 0 时 ，nread 代 表 我 们 可 以 向 输出 流 中 写 入 的 字 节 数 
目 。 最 后 注意 ， 缓 冲 区 要 由 我 们 手动 回收 。 


妆 分 配 函 数 alloc_buf() 返回 一 个 长 度 为 0 的 缓冲 区 时 ， 代 表 它 分 配 内 存 失 败 。 
在 这 种 情况 下 ， 读 取 的 回调 函数 会 被 错误 UV_ENOBUFS 唤醒 。libuv 同 时 也 会 继续 
尝试 从 流 中 读 取 数据 ， 所 以 如 果 你 想 要 停止 的 话 ， 必 须 明确 地 调用 uv_close() . 


当 nread 为 0 时 ， 代 表 已 经 没有 可 读 的 了 ， 大 多 数 的 程序 会 自动 忽略 这 


uvtee/main.c - Write to pipe 


typedef struct { 
uv_write_t req; 
uv_buf_t buf; 

} write req_t; 


void free write req(uv write t *req) { 
write req t *wr = (Write req t*) req; 
free(wr->buf .base); 
free(wr); 


} 


Void on stdout write(uv write t "reg, int status) {i 
free_write_req(req); 
} 


void on_file_write(uv_write_t *req, int status) { 
free_write_req(req); 
} 


void write data(uv_stream t "dest, size t size, uv buf t buf, uv_wi 
write rent *req = (write req t*) malloc(sizeof(write req t)); 
req->buf = uv_buf_init((char*) malloc(size), size); 
memcpy(req->buf.base, buf.base, size); 
uv_write((uv_write_t*) req, (uv_stream_t*)dest, &req->buf, 1, « 


} 
El — E: 


write _data() 开辟 了 一 块 地 址 空间 存储 从 缓冲 区 读 取出 来 的 数据 ， 这 块 缓存 不 
会 被 释放 ， 直 到 与 uv_write() 绑 定 的 回调 函数 执行 .为 了 实现 它 ， 我 们 用 结构 

体 write_redq t @B— “write request 和 一 个 buffer， 然 后 在 回调 函数 中 展开 它 。 
因为 我 们 复制 了 一 份 缓存 ， 所 以 我 们 可 以 在 两 个 write_data() 中 独立 释放 两 个 
缓存 。 我们 之 所 以 这 样 做 是 因为 ， 两 个 调用 write_data() 是 相互 独立 的 。 为 了 
保证 它们 不 会 因为 读 取 速度 的 原因 ， 由 于 共享 一 片 缓冲 区 而 损失 掉 独 立 性 ， 所 以 才 
开辟 了 新 的 两 块 区 域 。 当 然 这 只 是 一 个 简单 的 例子 ， 你 可 以 使 用 更 聪明 的 内 存 管理 
方法 来 实现 它 ， 比 如 引用 计数 或 者 缓冲 区 池 等 。 





WARNING 


你 的 程序 在 被 其 他 的 程序 调用 的 过 程 中 ， 有 意 无 意 地 会 向 pipe 写 入 数据 ， 这 样 
ad RA SIE. ， 你 最 好 在 初始 化 程序 的 时 候 加 入 这 
Ai: 
signal(SIGPIPE, SIG IGN) ° 


File change events 


所 有 的 现代 操作 系统 都 会 提供 相应 的 API 来 监视 文件 和 文件 夹 的 变化 (如 LinuxX 的 
inotify ，Darwin 的 FSEvents ，BSD 的 kqueue > Windows 的 
ReadDirectoryChangesW ，Solaris 的 event ports)。libuv 同 样 包括 了 这 样 的 文件 


监视 库 。 这 是 libuv 中 很 不 协调 的 部 分 ， 因 为 在 跨 平 台 的 前 提 上 ， 实 现 这 个 功能 很 
难 。 为 了 更 好 地 说 明 ， 我 们 现在 来 写 一 个 监视 文件 变化 的 命令 : 


./onchange <command> <file1> [file2] 


T 


实现 这 个 监视 器 ， 要 从 uv_fs_event_init() 开始 : 
onchange/main.c - The setup 


Se elef E Dat GC de CNE amgv E 
if (argc <= 2) í 
fprintf(stderr, "Usage: %s <command> <file1> [file2 ...]Nn' 
eur me 


} 


loop = uv_default loop(); 
command = argv[1]; 


while (argc-- > 2) í 
fprintf(stderr, "Adding watch on %sNn", argv[argc]); 
uv_fs_event_t *fs_event_req = malloc(sizeof(uv_fs_event_t)' 
uv_fs event _init(loop, fs_event_req); 
// The recursive flag watches subdirectories too. 
uv_fs_event_start(fs_event_req, run_command, argv[argc], UN 


} 


return uv_run(loop, UV_RUN_DEFAULT); 





圈 x 了 ss mo 


函数 uv_fs_event_start() 的 第 三 个 参数 是 要 监视 的 文件 或 文件 夹 。 最 后 一 个 参 
数 ，flags ， 可 以 是 : 


UV_FS_EVENT_WATCH_ENTRY 
UV_FS_EVENT_STAT = 2, 
UV_FS_EVENT_RECURSIVE = 4 


II 
= 


UV ES EVENT WATCH ENTRY 和 UV_FS_EVENT_STAT 不 做 任何 事情 (至 少 目前 是 这 
样 )， UV_FS_EVENT_RECURSIVE 可 以 在 支持 的 系统 平台 上 递归 地 监视 子 文件 夹 。 
在 回调 函数 run_command() 中 ， 接 收 的 参数 如 下 : 


"Lens cht -r =, Zo 
llbuv mi "ZZ 


1. uu Tas event t *handle -句柄 。 里 面 的 path 保 存 了 发 生 改 变 的 文件 的 地 

址 。 

2. const char *filename -如 果 目 录 被 监视 ， 它 代表 发 生 改 变 的 文件 名 。 只 
在 Linux 和 Windows 上 不 为 null， 在 其 他 平台 上 可 能 为 null。 

3. int flags - UV_RENAME 名 字 改 变 ， UV CHANGE 内 容 改 变 之 一 ， 或 者 他 
们 两 者 的 按 位 或 的 结果 ( | )。 

4. int status 一 当前 为 0. 


在 我 们 的 例子 中 ， 只 是 简单 地 打印 参数 和 调用 system() 运行 command. 
onchange/main.c - file change notification callback 


void run_command(uv_fs_event_t *handle, const char *filename, int « 
char path[1024]; 
Size t size 1023F 
// Does not handle error if path is longer than 1623. 
uv_fs_event_getpath(handle, path, &size); 
path[size] = 'N@'; 


fprintf(stderr, "Change detected in %s: ", path); 
if (events & UV_RENAME ) 

fprintf(stderr, "renamed" ); 
if (events & UV_CHANGE) 

fprintf(stderr, "changed"); 


fprintf(stderr, " %sNn", filename ? filename : ""); 
system(command); 





I S O 


D 
£ 


Networking 


在 libuv 中 使 用 网 络 编程 接口 不 会 像 在 BSD 上 使 用 socket 接 口 那 么 的 麻烦 ， 因 为 libuv 
上 所 有 的 都 是 非 阻塞 的 ， 但 是 原理 都 是 一 样 的 。 可 以 这 么 说 ，libuv 提 供 了 和 履 盖 了 恼 
人 的 ， 鹃 嗪 的 和 底层 的 任务 的 抽象 也 数 ， 比 如 使 用 BSD 的 socket 结 构 的 来 设置 
socket， 还 有 DNS 查找 ，libuv 还 调整 了 一 些 socket 的 参数 。 


在 网 络 |/O 〇 中 会 使 用 到 uv tept 和 uv udp t ° 


TCP 


TCP 是 面向 连接 的 ， 字 节 流 协议 ， 因 此 基于 libuv 的 stream 实 现 。 


server 
服务 器 端的 建立 流程 如 下 : 


1. uv_tcp_init #Ë > tcp J#8 ° 

2. uv tcp bind 绑 定 。 

3. uv_listen 建立 监听 ， 当 有 新 的 连接 到 来 时 ， 激 活 调用 回调 函数 。 
4. uv_accept 接收 链接 。 

5. 使 用 Stream 处 理 来 和 客户 端 通信 ° 


tcp-echo-serverlmain.c - The listen socket 
int main() í 
loop = uv_default_loop(); 


uv_tcp_t server; 
uv_tcp_init(loop, &server); 


Uv_ip4 addr("0.0.0.0", DEFAULT_PORT, &addr); 


uv_tcp_bind(&server, (const struct sockaddr*)&addr, 0); 
int r = uv_listen((uv_stream_t*) &server, DEFAULT_BACKLOG, ont 


H (G) Ad 
fprintf(stderr, "Listen error %sNn", uv_strerror(r)); 
Wetunn i; 

} 


return uv_run(loop, UV_RUN_DEFAULT); 








你 可 以 调用 uv_ip4_addr() 有 子 数 来 将 ip 地 址 和 端口 号 转换 为 Sockaddr in 结构 ， 这 
样 就 可 以 被 BSD 的 Socket 使 用 了 。 要 想 完 成 逆转 换 的 话 可 以 调 
用 uv_ip4 name() ° 


note 
对 应 ipv6 有 类 似 的 Uvip6* 


大 多 数 的 设置 函数 是 同步 的 ， 因 为 它们 不 会 消耗 太 多 cpu 资 源 。 到 
了 uv listen 这 名， 我 们 再 次 回 到 回调 函数 的 风格 上 来 。 第 二 个 参数 是 待 处 理 的 
连接 请 求 队列 一 最 大 长 度 的 请 求 连接 队列 。 


当 客 户 端 开 始 建立 连接 的 时 候 ， 回 调 函 数 on_new_connection 需要 使 
用 uv_accept 去 建立 一 个 与 客户 端 Socket 通 信 的 句柄 。 同 时 ， 我 们 也 要 开始 从 流 
中 读 取 数据 。 


tcp-echo-server/main.c - Accepting the client 


void on new connection(uv stream _ t *server, int status) { 
if (status < 0) í 
fprintf(stderr, "New connection error %s\n", uv_strerror (si 
M ser Gori! 
return; 


} 


UV Eent zeGlientz (UV ten El mallocisizeoriuv Een EN: 

uv_tcp_init(loop, client); 

if (uv_accept(server, (uv_stream_t*) client) == 0) í 
uv_read_start((uv stream t*) client, alloc_buffer, echo re 


} 
else í 
uv_close((uv_handle_t*) client, NULL); 





上 述 的 函数 集 和 stream 的 例子 类 似 ， 在 code 文 件 夹 中 可 以 找到 更 多 的 例子 。 记 得 在 
socket 不 需要 后 ， 调 用 uv_close。 如 果 你 不 需要 接受 连接 ， 你 甚至 可 以 在 uv_listen 
的 回调 函数 中 调用 uv_close ° 


client 


当 你 在 服务 器 端 完成 绑 定 监听 接收 的 操作 后 ， 在 客户 端 只 要 简单 地 调 
用 uv_tcp_connect ， 它 的 回调 函数 和 上 面 类 似 ， 具 体例 子 如 下 : 


UV Cen t* socket = (uv_tcp_t*)malloc(sizeof(uv_tcp_t)); 
uv_tcp_init(loop, socket); 


uv_connect_t* connect = (uv_connect_t*)malloc(sizeof(uv_connect_t)' 


struct sockaddr_in dest; 
uv_ip4_addr( "127.0.0.1", 80, &dest); 


uv_tcp_connect(connect, socket, dest, on_connect); 





aj 


4 LERE ° E] ñ on connect 会 被 调用 。 回 调 函 数 会 接收 到 一 个 
uv Connect t 结 构 的 数据 ， 它 的 handle 指向 通信 的 socket ° 





UDP 


用 户 数 据 报 协 议 (User Datagram Protocol) 提 供 无 连接 的 ， 不 可 靠 的 网 络 通 信 。 
此 ，libuv 不 会 提供 一 个 stream 实 现 的 形式 ， 而 是 提供 了 一 个 uv_udp_t g (4 
收 端 ) ， 和 一 个 uv_udp_send_t 句柄 (发送 端 ) ， 还 有 相关 的 函数 。 也 就 是 说 ， 


实际 的 读 写 api 与 正常 的 流 读 取 类 似 。 下 面 的 例子 展示 了 一 个 从 DCHP 服 务 器 获取 ip 
的 例子 。 


note 
你 必须 以 管理 员 的 权限 运行 Udp-dhcp， 因 为 它 的 端口 号 低 于 1024 


udp-dhcp/main.c - Setup and send UDP packets 


uv_loop_t *loop; 
uv_udp_t send_socket; 
uv_udp_t recv_socket; 


int main() í 
loop = uv_default loop(); 


uv_udp_init(loop, &recv_socket); 

struct sockaddr_in recv_addr; 

uv_ip4_addr( "0.0.0.0", 68, &recv_addr); 
uv_udp_bind(&recv_socket, (const struct sockaddr *)&recv_addr, 
uv_udp_recv_start(&recv_socket, alloc_buffer, on_read); 


uv_udp_init(loop, &send_socket); 

struct sockaddr_in broadcast_addr; 

uv_ip4_addr( "0.0.0.0", 6, &broadcast_addr); 
uv_udp_bind(&send_socket, (const struct sockaddr *)&broadcast_¿ 
uv_udp_set_broadcast(&send_socket, 1); 


uv_udp_send_t send_req; 
uv_buf_t discover_msg = make_discover_msg(); 


struct sockaddr_in send_addr; 
uv_ip4_addr ( "255.255.255.255", 67, &send_addr); 
uv_udp_send(&send_req, &send_socket, &discover_msg, 1, (const : 


return uv_run(loop, UV_RUN_DEFAULT); 


a C  - 





note 


ip 地 址 为 0.0.0.0， 用 来 绑 定 所 有 的 接口 。255.255.255.255 是 一 个 广播 地 址 ， 
也 意味 着 数据 报 将 往 所 有 的 子 网 接口 中 发 送 。 端 口号 为 0 代表 着 由 操作 系统 随 
机 分 配 一 个 端口 。 


首先 ， 我 们 设置 了 一 个 接收 的 Socket， 端 口号 为 68， 作 为 DHCP 客 户 端 ， 然 后 开始 

从 中 读 取 数据 。 它 会 接收 所 有 来 自 DHCP 服 务 器 的 返回 数据 。 我 们 设置 

了 UV_UDP_REUSEADDR 标记 ， 用 来 和 其 他 共享 端口 的 DHCP 客 户 端 和 平 共处 。 接 

着 ， 我 们 设置 了 一 个 类 似 的 发 送 Ssocket， 然 后 使 用 uv_udp_send 向 DHCP 服 务 器 
(在 67 端 口 ) 发 送 广播 。 


设置 广播 发 送 是 非常 党 必要 的 ， 否 则 你 会 接收 到 EACCES 错误 。 和 此 前 一 样 ， 如 果 在 
读 写 中 出 错 ， 返 回 码 <0 ° 
因为 UDP 不 会 连接 ， 因 此 回调 函数 会 接收 到 关于 发 送 者 的 额外 的 信息 。 


当 没 有 可 读数 据 后 ，nread 等 于 0。 如 果 addr 是 null ， 它 代表 了 没有 可 读数 据 
(回调 函数 不 会 做 任何 处 理 ) 。 如 果 不 为 null， 则 说 明了 从 addr 中 接收 到 一 个 空 的 
数据 报 。 如 果 flag 为 UV_UDP_PARTIAL ， 则 代表 了 内 存 分 配 的 空间 不 够 存放 接收 到 
的 数据 了 ， 在 这 种 情形 下 ， 操 作 系统 会 丢弃 存 不 下 的 数据 。 


udp-dhcp/main.c - Reading packets 


void on read(uv udp t ‘req, ssize t nread, const uv buf t “buf, Co 
if (nread < 0) { 
fprintf(stderr, "Read error %s\n", uv_err_name(nread)); 
uv_close((uv_handle t*) req, NULL); 
free(buf->base); 
return; 


} 


char sender[17] = í 0 }; 
uv_ip4_name((const struct sockaddr_in*) addr, sender, 16); 
fprintf(stderr, "Recv from %sNn", sender); 


// ... DHCP specific code 
unsigned int "as integer = (unsigned int*)buf->base; 
unsigned int ipbin = ntohl(as_integer[4]); 
unsigned char ip[4] = {0}; 
TME os 
for (= O 2 IEE) 
ip[i] = (ipbin >> i*8) & Oxff; 
fprintf(stderr, "Offered IP %d.%d.%d.%d\n", ip[3], ip[2], ip[1 


free(buf->base); 
uv_udp_recv_stop(req); 


RE 2 





UDP Options 

生存 时 间 (Time-to-live ) 
可 以 通过 uv_udp_set ttl 更 改 生存 时 间 。 

只 允许 IPV6 协 议 栈 
在 调用 uv_udp_bind 时 ， 设 置 UV_UDP_IPV60NLY 标示 ， 可 以 强制 只 使 用 
ipv6 ° 

组 播 


socket 也 支持 组 播 ， 可 以 这 么 使 用 : 


UV_EXTERN int uv_udp_set membership(uv_udp_t* handle, 
const char* multicast addr, 
const char* interface addr, 
uv_membership membership); 


其 中 membership 可 以 为 UV_JOIN_GROUP 和 UV_LEAVE_ GROUP ° 

这 里 有 一 篇 很 好 的 关于 组 播 的 文章 。 

可 以 使 用 uv_udp_set multicast_ loop 修改 本 地 的 组 播 。 

同样 可 以 使 用 uv_udp_set _multicast_ttl 修改 组 播 数据 报 的 生存 时 间 。 (RE 
生存 时 间 可 以 防止 数据 报 由 于 环 路 的 原因 ， 会 出 现 无 限 循环 的 问题 ) 。 


Querying DNS 


libuv 提 供 了 一 个 异步 的 DNS 解决 方案 。 它 提供 了 自己 的 getaddrinfo ° #6% $ 
数 中 你 可 以 像 使 用 正常 的 socket 操 作 一 样 。 让 我 们 来 看 一 下 例子 : 


dns/main.c 


Int main) i 
loop = uv_default loop(); 


struct addrinfo hints; 
hints.ai_family = PF_INET; 
hints.ai_socktype = SOCK_STREAM; 
hints.ai_protocol = IPPROTO_TCP; 
hints.ai_flags = 0; 


uv_getaddrinfo_t resolver; 


fprintf(stderr, rcsfreenodesnet is... "); 
int r = uv_getaddrinfo(loop, &resolver, on_resolved, "irc.freer 
if (r) { 
fprintf(stderr, "getaddrinfo call error %s\n", uv_err_name| 
return i: 
} 


return uv_run(loop, UV_RUN_DEFAULT); 


E === rFT 





如 果 uv _getaddrinfo 4 W3 RE > nf ERT > E] year, £ 2 A 8] 4) a 

数 。 在 函数 返回 后 ， 所 有 的 参数 将 会 被 回收 和 释放 。 主 机 地 址 ， 请 求 服 务 器 地 址 ， 
还 有 hints 的 结构 都 可 以 在 这 里 找到 详细 的 说 明 。 如 果 想 使 用 同步 请 求 ， 可 以 将 回调 
函数 设置 为 NULL ° 


在 回调 函数 on_resolved 中 ， 你 可 以 从 struct addrinfo(s) 链表 中 获取 返回 的 
IP， 最 后 需要 调用 uv_freeaddrinfo 回收 掉 链 表 。 下 面 的 例子 演示 了 回调 函数 的 


dns/main.c 


void on resolved(uv_getaddrinfo t Zresolver, nt status, struct adi 
if (status < 0) { 
fprintf(stderr, "getaddrinfo callback error %sNn", uv_err_r 
return; 


} 


char addr[17] = {'\0'}; 

uv_ip4_name((struct sockaddr_in*) res->ai_addr, addr, 16); 
fprintf(stderr, "%sNn", addr); 

uv_connect_t *connect_req = (uv_connect_t*) malloc(sizeof(uv_c« 
uv_tcp_t *socket = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); 
uv_tcp_init(loop, socket); 

uv_tcp_connect(connect_req, socket, (const struct sockaddr*) re 


uv_freeaddrinfo(res); 


4] RB 


libuv FF| JS 28 GT DNS% 8# ff 6 éi _getnameinfo ° 





Network interfaces 


可 以 调用 uv_interface_ addresses 获得 系统 的 网 络 接口 信息 。 下 面 这 个 简单 的 
例子 打印 出 所 有 可 以 获取 的 信息 。 这 在 服务 器 开始 准备 绑 定 IP 地 址 的 时 候 很 有 用 。 


interfaces/main.c 


#include <stdio.h> 
#include <uv.h> 


int main() í 
char buf[512]; 
uv_interface_address_t *info; 
int count, i; 


uv_interface addresses(&info, &count); 
i = count; 


printf("Number of interfaces: %dNn", count); 
while (i--) í 
uv_interface_address_t interface = info[i]; 


printf("Name: %sNn", interface.name); 
printf("Internal? %sNn", interface.is internal ? "Yes" : "| 


If (interface.address.address4.sin_family == AF_INET) í 
uv_ip4_name(&interface.address.address4, buf, sizeof(bı 
printf ("IPv4 address: %s\n", buf); 


else if (interface.address.address4.sin_family == AF_INET6 
uv_ip6_name(&interface.address.address6, buf, sizeof(bı 
printf ("IPv6 address: %s\n", buf); 


} 


DASE CENIA 
} 


uv Tree interface addresses(info, count); 
return 0; 


El 


is_internal 可 以 用 来 表示 是 否 是 内 部 的 |P。 由 于 一 个 物理 接口 会 有 多 个 IP 地 
址 ， 所 以 每 一 次 while 循 环 的 时 候 都 会 打印 一 次 。 





Threads 


等 一 下 ! 为 什么 我 们 要 聊 线 程 ? 事件 循环 (event loop) 不 应 该 是 用 来 做 web 编 程 

的 方法 吗 ? (如 果 你 对 event loop, 不 是 很 了 解 ， 可 以 看 这 里 )。 哦 ， 不 不 。 线 程 依旧 
是 处 理 器 完成 任务 的 重要 手段 。 线 程 因此 有 可 能 会 派 上 用 场 ， 虽 然 会 使 得 你 不 得 不 
艰难 地 应 对 各 种 原始 的 同步 问题 。 


线程 会 在 内 部 使 用 ， 用 来 在 执行 系统 调用 时 伪造 异步 的 假象 。libuv 通 过 线程 还 可 以 
使 得 程序 异步 地 执行 一 个 阻塞 的 任务 。 方 法 就 是 大 量 地 生成 新 线程 ， 然 后 收集 线程 
执行 返回 的 结果 。 


当下 有 两 个 占 主导 地 位 的 线程 库 : Windows 下 的 线程 实现 和 POSIX 的 pthread ° libuv 
的 线程 AP 与 pthread 的 API 在 使 用 方法 和 语义 上 很 接近 。 


值得 注意 的 是 ，libuv 的 线程 模块 是 自 成 一 体 的 。 比 如 ， 其 他 的 功能 模块 都 需要 依赖 
Tevent loop 和 回调 的 原则 ， 但 是 线程 并 不 是 这 样 。 它 们 是 不 受 约束 的 ， 会 在 需要 
的 时 候 阻 塞 ， 通 过 返回 值 产 生 信 号 错误 ， 还 有 像 接 下 来 的 这 个 例子 所 演示 的 这 样 ， 
不 需要 在 event loop 中 执行 。 


为 线程 API 在 不 同 的 系统 平台 上 ， 多 法 和 语义 表现 得 都 不 太 相 似 ， 在 支持 程度 上 
也 各 不 相同 。 考 虑 到 libuv 的 跨 平 台 特 性 ，libuv 支 持 的 线程 API 个 数 很 有 限 。 


最 后 要 强调 一 名 : 只 有 一 个 主线 程 ， 主 线程 上 只 有 一 个 event loop。 不 会 有 其 他 与 
主线 程 交互 的 线程 了 。 (除非 使 用 uv_async send ) ° 


Core thread operations 


下 面 这 个 例子 不 会 很 复杂 ， 你 可 以 使 用 uv_thread_create() 开始 一 个 线程 ， 再 
使 用 uv_thread_join() 等 待 其 结束 。 


thread-create/main.c 


Int maint)! 
int tracklen = 10; 
uv_thread t hare id; 
uv_thread t tortoise id; 
uv_thread Createiëhare id, hare, &tracklen); 
uv_thread create(&tortoise id, tortoise, &tracklen); 


uv_thread_ join(&hare_ id); 


uv_thread join(&tortoise id); 
re tuan 


TIP 


在 Unix 上 uv_thread t 只 是 pthread t 的 别名 , 但 是 这 只 是 一 个 具体 实现 ， 
不 要 过 度 地 依赖 它 ， 认 为 这 永远 是 成 立 的 。 


uv_thread_t 的 第 三 个 参数 指向 了 要 执行 的 函数 的 地 址 。 最 后 一 个 参数 用 来 传递 
自 定 义 的 参数 。 最 终 ， 函 数 hare 将 在 新 的 线程 中 执行 ， 由 操作 系统 调度 。 


thread-create/main.c 


void hare(void *arg) { 
int tracklen = *((int *) arg); 
while (tracklen) í 
tracklen--; 
sleep(1); 
fprintf(stderr, "Hare ran another step\n"); 


fprintf(stderr, "Hare done running!Nn"); 


uv_thread join 不 像 pthread join 那样 ， 允 许 线 线程 通过 第 二 个 参数 向 父 线 
程 返回 值 。 想 要 传递 值 ， 必 须 使 用 线程 间 通 信 |nter-thread communication ° 


Synchronization Primitives 


因为 本 教程 重点 不 在 线程 ， 所 以 我 只 罗列 了 libuv API 中 一 些 神奇 的 地 方 。 剩 下 的 你 
可 以 自行 阅读 pthreads 的 手册 。 


Mutexes 


libuv 上 的 互 斥 量 函 数 与 pthread 上 疮 在 一 一 映射 。 如 果 对 pthread 上 的 mutex 不 是 很 
了 解 可 以 看 这 里 。 


libuv mutex functions 


UV EXTERN int uv mutex init(uv mutex t* handle); 
UV_EXTERN void uv mutex destroy(uv mutex t* handle); 
UV EXTERN, void uv mutex lock(uv mutex t* handle); 
UV_EXTERN int uv mutex trylock(uv mutex t* handle); 
UV_EXTERN void uv_mutex unlock(uv_mutex_t* handle); 


uv_mutex_init 与 uv_mutex_trylock 在 成 功 执行 后 ， 返 回 0， 或 者 在 错误 时 ， 
返回 错误 码 。 


如 果 libuv 在 编译 的 时 候 开 启 了 调试 模式 ， uv_mutex_destroy() , 
uv_mutex_lock() 和 uv_mutex_unlock() 会 在 出 错 的 地 方 调 用 abort() 中 
B o 254269 ° uv_mutex_trylock() 也 同样 会 在 错误 发 生 时 中 断 ， 而 不 是 返 

回 EAGAIN 和 EBUSY ° 


递归 地 调用 互 斥 量 函数 在 某 些 系统 平台 上 是 支持 的 ， 但 是 你 不 能 太 过 度 依赖 。 因 为 
例如 在 BSD 上 递归 地 调用 互 不 量 函 数 会 返回 错误 ， 上 比如 你 准备 使 用 互 斥 量 函 数 给 一 
个 已 经 上 锁 的 临界 区 再 次 上 人 锁 的 时 候 ， 就 会 出 错 。 比 如 ， 像 下 面 这 个 例子 : 


uv_mutex_lock(a_mutex); 

uv_thread_create(thread_id, entry, (void *)a_mutex); 
uv_mutex_lock(a_mutex); 

// more things here 


可 以 用 来 等 待 其 他 线程 初始 化 一 些 变 量 然后 释放 a mutex 锁 ， 但 是 第 二 次 调 
用 uv_mutex_lock() ,在 调试 模式 下 会 导致 程序 前 溃 ， 或 者 是 返回 错误 。 


NOTE 
在 linux 中 是 支持 递归 上 和 锁 的 ， 但 是 在 libuv 的 AP| 中 并 未 实现 。 


Lock 


读 写 锁 是 更 细 粒 度 的 实现 机 制 。 两 个 读者 线程 可 以 同时 从 共享 区 中 读 取 数 据 。 当 读 
者 以 读 模 式 占有 读 写 锁 时 ， 写 者 不 能 再 占有 它 。 当 写 者 以 写 模式 占有 这 个 锁 时 ， 其 
他 的 写 者 或 者 读者 都 不 能 占有 它 。 读 写 锁 在 数据 库 操作 中 非常 常见 ， 下 面 是 一 个 玩 
具 式 的 例子 : 


ocks/main.c - simple rwlocks 


#include <stdio.h> 
#include <uv.h> 


uv_barrier_t blocker; 
uv_rwlock_t numlock; 
int shared num: 


void reader(void *n) 
{ 
int num = *(int *)n; 
a me ol 
ror (q s 0p DEE Ee E 
uv_rwlock_rdlock(&numlock); 
printf ("Reader %d: acquired lock\n", num); 
printf("Reader %d: shared num = %d\n", num, shared_num); 
uv_rwlock_rdunlock(&numlock); 
printf("Reader %d: released lockNn", num); 


} 


uv_barrier wait(&blocker ); 


} 


void writer(void *n) 
{ 
int num = *(int *)n; 
WME e 
ror (L S op sb < 25 E RER 
uv_rwlock_wrlock(&numlock); 
printf("Writer %d: acquired lockNn", num); 
shared _num++; 
printf("Writer %d: incremented shared num = %d\n", num, shé 
uv_rwlock_wrunlock(&numlock); 
printf("writer %d: released lock\n", num); 
} 


uv_barrier_wait(&blocker); 


int main() 
uv_barrier_init(&blocker, 4); 


shared_num = 0; 
uv_rwlock_init(&numlock); 


uv_thread_t threads[3]; 

int thread_nums[] = {1, 2, 1); 

uv_thread create(&threads[0], reader, &thread nums[0]); 
uv_thread create(&threads[1], reader, &thread nums[1]); 


uv_thread create(&threads[2], writer, &thread nums[2]); 


uv_barrier wait(&blocker ); 
uv_barrier_destroy(&blocker); 


uv_rwlock_destroy(&numlock); 
return 0; 





试 着 来 执行 一 下 上 面 的 程序 ， 看 读者 有 多 少 次 会 同步 执行 。 在 有 多 个 写 者 的 时 候 ， 
调度 器 会 给 予 他 们 高 优先 级 。 因 此 ， 如 果 你 加 入 两 个 读者 ， 你 会 看 到 所 有 的 读者 趋 
向 于 在 读者 得 到 加 锁 机 会 前 结 


在 上 面 的 例子 中 ， 我 们 也 使 用 了 屏障 。 因 此 主线 程 来 等 待 所 有 的 线程 都 已 经 结束 ， 
最 后 再 将 屏障 和 和 锁 一 块 回收 。 


Others 


libuv 同 样 支持 信号 量 ， 条 件 变量 和 屏障 ， 而 且 API 的 使 用 SE 
类 似 。 (如 果 你 对 上 面 的 三 个 名 词 还 不 是 很 就 ， 可 以 看 这 里 ， 这 里 ， 这 里 ) o 
。 多 个 


还 有 ，libuv 提 供 了 一 个 简单 匈 用 的 光 数 uv_once() ° 线程 调用 这 个 函数 ， 
数 可 以 使 用 一 个 uv_once_t 和 一 个 指向 特定 函数 的 指针 ， 最 终 只 有 一 个 线程 SCH 
行 这 个 特定 函数 ， 并 且 这 个 特定 函数 只 会 被 调用 一 次 : 


nneralrze Otter SE 
static uv_once t once only = UV_ONCE_INIT 


int i = O; 


void increment() í 


i++; 
} 
void Chreadt(i d 
e WOR =/ 
uv_once(once_only, increment); 
} 
void thread2() í 
XWomke Z 
uv_once(once_only, increment); 
} 
ne maint) 人 
Ze spawn threads XY 
} 


当 所 有 的 线程 执行 于 完毕 时 * == 


在 libuv 的 v0.11.11 版 本 里 ， 推 出 了 uv_key_t 结 构 和 操作 线程 局 部 存储 TLS 的 APl， 使 
用 方法 同样 和 pthread 类 似 。 


libuv work queue 


uv_queue_work() 是 一 个 便利 的 函数 ， 它 使 得 一 个 应 用 程序 能 够 在 不 同 的 线程 运 
行 任务 ， 当 任务 完成 后 ， 回 调 函 数 将 会 被 触发 。 它 看 起 来 好 像 很 简单 ， 但 是 它 趴 正 
吸引 人 的 地 方 在 于 它 能 够 使 得 任何 第 三 方 的 库 都 能 以 event-loop 的 方式 执行 。 当 使 
用 event-loop 的 时 候 ， 最 重要 的 是 不 能 让 loop 线 程 阻塞 ， 或 者 是 执行 高 cpu 占 用 的 程 
序 ， 因 为 这 样 会 使 得 loop 慢 下 来 ，loop event 的 高 效 特性 也 不 能 得 到 很 好 地 发 挥 。 


然而 ， 很 多 带 有 阻塞 的 特性 的 程序 (比如 最 常见 的 |/O 〇 ) 使 用 开辟 新 线程 来 响应 新 请 
求 (最 经 典 的 ' 一 个 客户 ， 一 个 线程 ' 模 型 )。 使 用 event-loop 可 以 提供 另 一 种 实现 的 方 
式 。libuv 提 供 了 一 个 很 好 的 抽象 ， 使 得 你 能 够 很 好 地 使 用 它 。 


下 面 有 一 个 很 好 的 例子 ， 灵 感 来 自 <<nodejs is cancer>>。 我 们 将 要 执行 fibonacci 
数列 ， 并 且 睡 眠 一 段 时 间 ， 但 是 将 阻塞 和 cpu 占 用 时 间 长 的 任务 分 配 到 不 同 的 线 
程 ， 使 得 其 不 会 阻塞 event loop 上 的 其 他 任务 。 


dueue-work/main.c - lazy fibonacci 


void fib(uv work t *req) í 
int n = *(int *) req->data; 
if (random() % 2) 
sleep(1); 
else 
sleep(3); 
long fib = fib_(n); 
fprintf(stderr, "%dth fibonacci is %luNn", n, fib); 
} 


void after_fib(uv_work_t *req, int status) { 
fprintf(stderr, “Done calculating %dth fibomacciNnm", *(int *) 1 


Aq O 了 著 


任务 函数 很 简单 ， 也 还 没有 运行 在 线程 之 上 。 uv work t 是 关键 线索 ， 你 可 以 通 
过 void *data 传递 任何 数据 ， 使 用 它 来 完成 线程 之 间 的 沟通 任务 。 但 是 你 要 确 
信 ， 当 你 在 多 个 线程 都 在 运行 的 时 候 改 变 某 个 东西 的 时 候 ， 能 够 使 用 适当 的 锁 。 





触发 器 是 uv_queue_work 
queue-work/main.c 


int main() { 
loop = uv_default loop(); 


int data[FIB_UNTIL]; 
Uv_work_t req[FIB_ UNTIL]; 
Le ILe 
for (i = 0; i < FIB_UNTIL; i++) £ 
data[i] = i; 
req[i].data = (void *) &data[i]; 
Uv_queue work(loop, &req[i], fib, after_fib); 


} 


return uv_run(loop, UV_RUN_DEFAULT); 


线程 函数 fbi() 将 会 在 不 同 的 线程 中 运行 ， 传 入 uv work t 结构 体 参 数 ， 一 旦 fib() 函 
数 返 回 ，after_fib() 会 被 event loop 中 的 线程 调用 ， 然 后 被 传 入 同样 的 结构 体 。 


为 了 封装 阻塞 的 库 ， 常 见 的 模式 是 用 baton 来 交换 数据 。 


从 libuv 0.9.4 版 后 ， 添 加 了 函数 uv_cancel() 。 它 可 以 用 来 取消 工作 队列 中 的 任 
务 。 只 有 还 未 开始 的 任务 可 以 被 取消 ， 如 果 任 务 已 经 开始 执行 或 者 已 经 执行 完 
毕 ， uv cancel() 调用 会 失败 。 


当 用 户 想 要 终止 程序 的 时 候 ， uv_cancel() 可 以 用 来 清理 任务 队列 中 的 等 待 执行 
的 任务 。 例 如 ， 一 个 音乐 播放 器 可 以 以 歌手 的 名 字 对 歌曲 进行 排序 ， 如 果 这 个 时 候 
用 户 想 要 退出 这 个 程序 ， uv_cancel() 就 可 以 做 到 快速 退出 ， 而 不 用 等 待 执行 完 
任务 队列 后 ， 再 退出 。 


让 我 们 对 上 述 程序 做 一 些 修改 ， 用 来 演示 uu Cancel) 的 用 法 。 首 先 让 我 们 注册 
一 个 处 理 中 断 的 元 数 。 


queue-cancel/main.c 


int main() { 
loop = uv_default loop(); 


int data[FIB UNTIL]; 
INE ako 
for (i = 0; i < FIB UNTIL; i++) { 
data[i] = i; 
fib_reqs[i].data = (void *) &data[i]; 
Uv_queue work(loop, &fib_reqs[i], fib, after_fib); 
} 


uv_signal t sig; 
uv_signal init(loop, &sig); 
uv_signal start(&sig, signal handler, SIGINT); 


return uv_run(loop, UV_RUN_DEFAULT); 


当 用 户 通 过 Ctrl+C 触发 信号 时 ， uv_cancel() 回收 任务 队列 中 所 有 的 任务 ， 如 
果 任 务 已 经 开始 执行 或 者 执行 完毕 ， uv_cancel() 返回 0。 


queue-cancel/main.c 


void signal hand leriuv sonal t *req, int signum) 


{ 
printf("signal received!Nn"); 
IME al 
for (i = 0; i < FIB_UNTIL; i++) { 
uv_cancel((uv_req_t*) &fib_reqs[i]); 
} 
uv_signal stop(req); 
} 


对 于 已 经 成 功 取 消 的 任务 ， 他 的 回调 了 泡 数 的 参数 status 会 被 设置 
为 UV_ECANCELED 。 


queue-cancel/main.c 


vord after Tibiuv work C reg, int status) 4 
if (status == UV_ECANCELED ) 
fprintf(stderr, "Calculation of %d cancelled.\n", *(int *) 


} 
e O 





uv_cancel() 函数 同样 可 以 用 在 uv_fs_t 和 uv_getaddrinfo t 请 求 上 。 对 于 
一 系列 的 文件 系统 操作 函数 来 说 ， uv _ fs t.errorno 会 同样 被 设置 
为 UV_ECANCELED ° 


Tip 


一 个 良好 设计 的 程序 ， 应 该 能 够 终止 一 个 已 经 开始 运行 的 长 耗 时 任务 。 
Such a worker could periodically check for a variable that only the main 
process sets to signal termination. 


Inter-thread communication 


很 多 时 候 ， 你 希望 正在 运行 的 线程 之 间 能 够 相互 发 送 消息 。 例 如 你 在 运行 一 个 持续 
时 间 长 的 任务 〈 可 能 使 用 uv_queue_work) ， 但 是 你 需要 在 主线 程 中 监视 它 的 进度 
情况 。 下 面 有 一 个 简单 的 例子 ， 演 示 了 一 个 下 载 管 理 程序 向 用 户 展示 各 个 下 载 线程 
的 进度 。 


progress/main.c 


SE? 
e ke ur CT 
libuv i 


uv_loop_t *loop; 
uv_async_t async; 


int main() { 
loop = uv_default_loop(); 


uv_work_t req; 
Int size = 10240; 
reg. data = (void*) &size; 

uv_async_init(loop, &async, print_progress); 
Uv_queue work(loop, &req, fake download, after); 


return uv_run(loop, UV_RUN_DEFAULT); 


x. 的 线程 通信 是 基于 event-loop 的 ， 所 以 尽管 所 有 的 线程 都 可 以 是 发 送 方 ， 
但 是 只 有 在 event-loop 上 的 线程 可 以 是 接收 方 (或 者 说 event-loop 是 接收 方 ) 。 在 上 

述 的 代码 中 ， 当 有 异步 监视 者 接收 到 信号 的 时 候 ，libuv 会 激发 回调 函数 

(print progress) ° 


WARNING 


应 该 注意 : 因为 消息 的 发 送 是 异步 的 , 当 uv_async_send 在 另外 一 个 线程 中 被 
调用 后 ， 回 调 函 数 可 能 会 立即 被 调用 , 也 可 能 在 稍 后 的 某 个 时 刻 被 调用 。 
libuv 也 有 可 能 多 次 调用 uv_async_send ， 但 只 调用 了 一 次 回调 函数。 唯一 可 
以 保证 的 是 : 线程 在 调用 uv_async_send 之 后 回调 函数 可 至 少 被 调用 一 次 。 
如 果 你 没有 未 调用 的 uv_async_send ,那么 A HAARATA 被 调用 。 
如 果 你 调用 了 两 次 (以 上 ) 的 uv_async_send , m libuv 暂时 还 没有 机 会 运行 回 
AAR, 则 libuv 可 能 会 在 多 次 调用 UV async send 后 只 调用 一 次 回调 总数 ， 
你 的 回调 函数 绝对 不 会 在 一 次 事件 中 被 调用 两 次 (或 多 次 ) ° 


progress/main.c 


void Take download(uv work t *req) í 

int size = *((int*) req->data); 

int downloaded = o: 

double percentage; 

while (downloaded < size) í 
percentage = downloaded*100.0/size; 
async.data = (void*) &percentage; 
uv_async_send(&async); 


sleep(1); 
downloaded += (200+random())%1000; // can only download ma: 
// but at least a 200; 





在 上 述 的 下 载 函 数 中 ， 我 们 修改 了 进度 显示 器 ， 使 用 uv_async_ | 度 信 
息 。 要 记 住 : uv_async_send 同样 是 非 阻塞 的 ， 调用 后 会 立即 返 


progress/main.c 


void print progress(uv_async t *handle) + 
double percentage = *((double*) handle->data); 
fprintf(stderr, "Downloaded %.2f%%\n", percentage); 


函数 print progress 是 标准 的 libuv 模 式 ， 从 监视 器 中 抽取 数据 。 
最 后 最 重要 的 是 把 监视 器 回收 。 


progress/main.c 


void after(uv work t *req, int status) í 
fprintf(stderr, "Download completeNn"); 
uv_close((uv_handle_t*) &async, NULL); 


在 例子 的 最 后 ， 我 们 要 说 下 data 域 的 滥用 ，bnoordhuis 指 出 使 用 data ATA 
存在 线程 安全 问题 ， uv_async_send() 事实 上 只 是 唤醒 了 event-loop。 可 以 使 用 
互 矿 量 或 者 读 写 锁 来 保证 执行 顺序 的 正确 性 。 


Note 


互 矿 量 和 读 写 锁 不 能 在 信号 处 理 函 数 中 正确 工作 ， 但 是 uv_async_send 可 
以 。 


libuv 中 文教 程 


一 种 需要 使 用 uv_async_send 的 场景 是 ， 当 调用 需要 线程 交互 的 库 时 。 例 如 ， 举 
一 个 在 node.js 中 V8 引擎 的 例子 ， 上 下 文 和 对 象 都 是 与 v8 引擎 的 线程 绑 定 的 ， 从 另 
一 个 线程 中 直接 向 v8 请 求 数据 会 导致 返回 不 确定 的 结果 。 但 是 ， 考 虑 到 现在 很 多 
nodejs 的 模块 都 是 和 第 三 方 库 绑 定 的 ， 可 以 像 下 面 一 样 ， 解 决 这 个 问题 : 


1. 在 node 中 ， 第 三 方 库 会 建立 javascript 的 回调 函数 ， 以 便 回调 函数 被 调用 时 ， 
能 够 返回 更 多 的 信息 。 


var lib = require('lib'); 
lib.on_progress(function() í 

console.log("Progress"); 
)); 


lib.do(); 


// do other stuff 


2. lib.do 应 该 是 非 阻 塞 的 ， 但 是 第 三 方 库 却 是 阻塞 的 ， 所 以 需要 调 

用 uv_queue_work Až ° 

3. 在 另外 一 个 线程 中 完成 任务 想 要 调用 progress 的 回调 函数 ， 但 是 不 能 直接 与 
V8 通信 ， 所 以 需要 uv_async_send H% ° 

4. 在 主线 程 (v8 线程 ) 中 调用 的 异步 回调 函数 ， 会 在 v8 的 配合 下 执行 javscript 
的 回调 函数 。 (也 就 是 说 ， 主 线程 会 调用 回调 函数 ， 并 且 提 供 v8 解 析 javascript 
的 功能 ， 以 便 其 完成 任务 ) ° 


线程 40 


Processes 


libuv 提 供 了 相当 多 的 子 进程 管理 函数 ， 并 且 是 跨 平 台 的 ， 还 允许 使 用 stream ， 或 者 
说 pipe 完 成 进程 间 通 信 。 

在 UNIX 中 有 一 个 共识 ， 就 是 进程 只 做 一 件 事 ， 并 把 它 做 好 。 因 此 ， 进 程 通常 通过 创 
建 子 进程 来 完成 不 同 的 任务 (例如 ， 在 shell 中 使 用 pipe) 。 一 个 多 进程 的 ， 通 过 消 
息 通信 的 模型 ， 总 比 多 线程 的 ， 共 享 内 存 的 模型 要 容易 理解 得 多 。 


当前 一 个 比较 常见 的 反对 事件 驱动 编程 的 原因 在 于 ， 其 不 能 很 好 地 利用 现代 多 核 计 
算 机 的 优势 。 一 个 多 线程 的 程序 ， 内 核 可 以 将 线程 调度 到 不 同 的 cpu 核 心中 执行 ， 
以 提高 性 能 。 但 是 一 个 event-loop 的 程序 只 有 一 个 线程 。 实 际 上 ， 工 作 区 可 以 被 分 
配 到 多 进程 上 ， 每 一 个 进程 执行 一 个 event-loop， 然 后 每 一 个 进程 被 分 配 到 不 同 的 
cpu 核 心中 执行 。 


Spawning child processes 


一 个 最 简单 的 用 途 是 ， 你 想 要 开始 一 个 进程 ， 然 后 知道 它 什么 时 候 终 止 。 需 要 使 
用 uv_spawn 完成 任务 : 


spawn/main.c 


uv_loop_t *loop; 
uv_process_t child reg: 
uv_process_options_t options; 
int main() { 

loop = uv_default_loop(); 


char* args[3]; 
args[0] = "mkdir"; 
args[1] "est chimi 
args[2] NULL; 


options.exit cb = on_exit; 
options.file = "mkdir"; 
options.args = args; 


ED E 
if ((r = uv Späwpnt Loop, &child reg, &options))) í 
fprintf(stderr, "%sNn", uv_strerror(r)); 
return 1; 
} else í 
fprintf(stderr, "Launched process with ID %dNn", child req. 
} 


return uv_run(loop, UV_RUN_DEFAULT); 


Ki = wë F: 
Note 


由 于 上 述 的 options 是 全 局 变量 ， 因 此 被 初始 化 为 0。 如 果 你 在 局 部 变量 中 定义 
options， 请 记得 将 所 有 没 用 的 域 设 为 0 





uv_process_options_t options = {0}; 


uv_process_t X £ 1E2J AR ° PT KIANA uv_process_options_t 4 
置 ， 为 了 简单 地 开始 一 个 进程 ， 你 只 需要 设置 fle 和 args，file 是 要 执行 的 程序 ， 
args 是 所 需 的 参数 (和 c 语 言 中 main 有 函数 的 传 入 参数 类 似 ) 。 因 为 uv_spawn 在 内 
部 使 用 了 execvp， 所 以 不 需要 提供 绝对 地 址 。 遵 从 惯例 ， 实 际 传 入 参数 的 数目 要 比 
需要 的 参数 多 一 个 ， 因 为 最 后 一 个 参数 会 被 设 为 NULL 。 


在 函数 uv_spawn 被 调用 之 后 ， uv_ process t.pid 会 包含 子 进 程 的 id ° 
回调 函数 on_exit() 会 在 被 调用 的 时 候 ， 传 入 exit 状 态 和 导致 exit 的 信号 。 


spawn/main.c 


void on_exit(uv process_ t "reg, int64_t exit status, int term signi 
fprintf(stderr, "Process exited with status %" PRId64 ", signa: 
uv_close((uv_handle t*) req, NULL); 


1 
在 进程 关闭 后 ， 需 要 回收 handler。 














Changing process parameters 


在 子 进程 开始 执行 前 ， 你 可 以 通过 使 用 uv_process_options t 设置 运行 环境 。 


Change execution directory 


设置 uv_process_options_t,cwd ， 更 改 相 应 的 目录 。 


Set environment variables 


uv_process_options_t.env 的 格式 是 以 nul 为 5 其 中 每 一 个 
字符 囊 的 形式 都 是 VAR=VALUE 。 这 些 值 用 来 设置 进程 的 环境 变量 。 如 果子 进程 想 
要 继承 父 进程 的 环境 变量 ， 就 将 uv_process_options_t,env 设 为 nul ° 


Option flags 


通过 使 用 下 面 标识 的 按 位 或 的 值 设 置 uv_process_options_t.flags 的 值 ， 可 以 
定义 子 进程 的 行为 : 


e UV_PROCESS_SETUID -将 子 进程 的 执行 用 户 id (UID) 设置 
为 uv_process options t.uid 中 的 值 。 
e UV_PROCESS_SETGID -将 子 进程 的 执行 组 id(GID) 设 置 
为 uv_process options t.gid 中 的 值 。 
只 有 在 unix 系 的 操作 系统 中 支持 设置 用 户 id 和 组 id， 在 windows 下 设置 会 失 
败 ， uv _ spawn 会 返回 UV_ENOTSUP ° 
e UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS -在 windows 
上 ， uv_process_options_t,args 参数 不 要 用 引号 包 里 。 此 标记 对 Unix 
无 效 。 
e UV_PROCESS_DETACHED -在 新 会 话 (Session) 中 局 却 ST 程 ， 这 样子 进 
就 可 以 在 父 进程 退 出 后 继续 进行 。 请 看 下 面 的 例子 


Detaching processes 


使 用 标识 UV_PROCESS _ E 可 以 启动 守护 进程 (daemon) ， 或 者 是 使 得 子 进 
程 从 父 进程 中 独立 出 来 ， 进程 的 退出 就 不 会 影响 到 它 。 


detach/main.c 


int main() { 
loop = uv_default loop(); 


char* args[3]; 


args[0] = "sleep"; 
args[1] = "100"; 
args[2] = NULL; 


options.exit_cb = NULL; 

options.file = "sleep"; 

options.args args; 

options.flags = UV_PROCESS_DETACHED; 


TE es 

if ((r = uv_spawn(loop, &child_req, &options))) { 
fprintf(stderr, "%s\n", uv_strerror(r)); 
return T: 


} 
fprintf(stderr, "Launched sleep with PID %d\n", child_req.pid), 
uv_unref((uv_handle_t*) &child_req); 


return uv_run(loop, UV_RUN_DEFAULT); 
al sa Š 


记 住 一 点 ， 就 是 handle 会 始终 监视 着 子 进 程 ， 所 以 你 的 程序 不 会 退 
H o uv_unref() 会 解除 handle ° 





Sending signals to processes 

libuv 打 包 了 unix 标 准 的 kill(2) 系统 调用 ， 并 且 在 windows 上 实现 了 一 个 类 似 用 
法 的 调用 ， 但 要 注意 : 所 有 的 SIGTERM ， SIGINT 和 SIGKILL 都 会 导致 进程 的 
中 断 。 uv kill 函数 如 下 所 示 : 


uv ert E uv_kill(int pid, int signum); 


对 于 用 libuv 启 动 的 进程 ， 应 该 使 用 uv_process_kill 终止 ， 它 会 
以 uv_process_t 作为 第 一 个 参数 ， 而 不 是 pid。 当 使 用 uv process _ kill E: 
记得 使 用 uv_close 关闭 uv_process_t ° 


Signals 


libuv 对 unix 信 号 和 一 些 windows 下 类 似 的 机 制 ， 做 了 很 好 的 打包 。 


使 用 uv_signal init 初始 化 handle ( uv_signal t ) ， 然 后 将 它 与 loop 关 联 。 
为 了 使 用 handle 监 听 特 定 的 信号 ， 使 用 uv_signal_start() 函数 。 每 一 个 handle 
只 能 与 一 个 信号 关联 ， 后 续 的 uv_signal start 会 履 盖 前 面 的 关联 。 使 

用 uv_signal_stop 终止 监听 。 下 面 的 这 个 小 例子 展示 了 各 种 用 法 : 


signal/main.c 


#include <stdio.h> 
#include <stdlib.h> 
#include <unistd.h> 
#include <uv.h> 


uv_loop_t* create_loop() 


{ 
uv_loop_t *loop = malloc(sizeof(uv_loop_t)); 
if (loop) í 
uv_loop_init(loop); 
} 
return loop; 
} 


void signal handler(uv signal t “handle, int signum) 
{ 
printf("Signal received: %d\n", signum); 
uv_signal_stop(handle); 


} 


// two signal handlers in one loop 
void thread1 worker(void *userp) 


{ 


uv_loop_t *loop1 = create_loop(); 


uv_signal_t sigla, sigib; 
uv_signal_init(loop1, &sigia); 
uv_signal_start(&sigilia, signal_handler, SIGUSR1); 


uv_signal_init(loop1, &sig1b); 
uv_signal_start(&sig1b, signal_handler, SIGUSR1); 


uv_run(loop1, UN RUN DEFAULT); 
} 


// two signal handlers, each in its own loop 
void thread2 worker(void *userp) 
{ 
uv_loop_t *loop2 
uv_loop_t *loop3 


= create_loop(); 

= create_loop(); 

uv_signal_t sig2; 

uv_signal_init(loop2, &sig2); 
uv_signal_start(&sig2, signal_handler, SIGUSR1); 


uv_signal_t sig3; 
uv_signal_init(loop3, &sig3); 
uv_signal_start(&sig3, signal_handler, SIGUSR1); 
while (uv_run(loop2, UV_RUN_NOWAIT) || uv_run(loop3, UV RUN NO 
} 
ime maint) 
printf("PID %dNn", getpid()); 


uv_thread_t thread1, thread2; 


uv_thread_create(&thread1, thread1 worker, 0); 
uv_thread_create(&thread2, thread2 worker, 0); 


uv_thread_join(&thread1); 
uv_thread_join(&thread2); 
return 0; 





Note 


uv_run(loop, UV RUN NOWAIT) 和 uv_run(loop, UN RUN ONCE) 非常 
像 ， 因 为 它们 都 只 处 理 一 个 事件 。 但 是 不 同 在 于 ，UV_RUN_ONCE 会 在 没有 


任务 的 时 候 阻 塞 ， 但 是 UV_RUN_NOWAIT 会 立刻 返回 。 我 们 使 用 NOWAIT 
这 样 才 使 得 一 个 loop 不 会 因为 另外 一 个 loop 没 有 要 处 理 的 事件 而 挨 饿 。 


当 向 进程 发 送 SIGUSR1 ， 你 会 发 现 signal_handler 函 数 被 激发 了 4 次 ， 每 次 都 对 应 
一 个 uv_signal t 。 然 后 signal_handler 调 用 uv_signal_stop 终 止 了 每 一 

个 uv_signal t ， 最 终 程 序 退 出 。 对 每 个 handler 有 函数 来 说 ， 任 务 的 分 配 很 重要 。 
一 个 使 用 了 多 个 event-loop 的 服务 器 程序 ， 只 要 简单 地 给 每 一 个 进程 添加 信号 
SIGINT 监 视 器 ， 就 可 以 保证 程序 在 中 断 退 出 前 ， 数 据 能 够 安全 地 保存 。 


Child Process UO 


一 个 正常 的 新 产生 的 进程 都 有 自己 的 一 套 文件 描述 符 映射 表 ， 例 如 0，1，2 分 别 对 
应 stdin > stdout 和 stderr 。 有 时 候 父 进程 想 要 将 自己 的 文件 描述 符 映 射 表 
分 享 给 子 进 程 。 例 如 ， 你 的 程序 启动 了 一 个 子 命令 ， 并 且 把 所 有 的 错误 信息 输出 到 
log 文 件 中 ， 但 是 不 能 使 用 stdout 。 因 此 ， 你 想 要 使 得 你 的 子 进程 和 父 进 程 一 
样 ， 拥 有 stderr 。 在 这 种 情形 下 ，libuv 提 供 了 继承 文件 描述 符 的 功能 。 在 下 面 的 
例子 中 ， 我 们 会 调用 这 么 一 个 测试 程序 : 


proc-streams/test.c 


#include <stdio.h> 
int main() 


fprintf(stderr This ys stderr Nn ), 
printi Denge e ls stdoueNn 0 
engl ot-191g 


实际 的 执行 程序 proc-streams 在 运行 的 时 候 ， 只 向 子 进 程 分 享 stderr 。 使 
用 uv_process_options t 的 stdio 域 设 置 子 进程 的 文件 描述 符 。 首 先 设 

Ë stdio_count ， 定 义 文件 描述 符 的 个 数 。 uv_process_options_t,stdio 是 
一 个 uv_stdio_container_t 数组 。 定 义 如 下 : 


typedef struct uv_stdio_container_s { 
uv_stdio flags flags; 


upnion P£ 
uv_stream_t* stream; 
sime rols 
} data; 
} uv_stdio container_t; 


上 边 的 flag 值 可 取 多 种 。 比 如 ， 如 果 你 不 打算 使 用 ， 可 以 设置 为 UV_IGNORE 。 如 
果 与 stdio 中 对 应 的 前 三 个 文件 描述 符 被 标记 为 UV_IGNORE ， 那 么 它们 会 被 重 定向 
到 /dev/null ° 

因为 我 们 想 要 传递 一 个 已 经 存在 的 文件 描述 符 ， 所 以 使 用 UV_INHERIT_FD 。 
此 ，fd 被 设 为 stderr。 


proc-streams/main.c 


Se Le u EH LEES E 
loop = uv_default_loop(); 


K Ka . * d 
/ ... / 


options.stdio_count = 3; 
uv_stdio_container_t child stdio[3]; 
child_stdio[0].flags UV_IGNORE; 
child_stdio[1].flags UV_IGNORE; 
child_stdio[2].flags = UV_INHERIT_FD; 
child_stdio[2].data.fd = 2; 
options.stdio = child_stdio; 


options.exit_cb = on_exit; 
options.file = args[0]; 
options.args args; 


LNE. [PD 

if ((r = uv_spawn(loop, &child_req, &options))) { 
fprintistderr ew%s\ nm uvestrerror(r Ds, 
Ceturn dl,; 


} 


return uv_run(loop, UV_RUN_DEFAULT); 


这 时 你 启动 proc-streams， 也 就 是 在 main 中 产生 一 个 执行 test 的 子 进程 ， 你 只 会 看 
到 “This is stderr。 你 可 以 试 着 设置 stdout 也 继承 父 进程 。 


同样 可 以 把 上 述 方法 用 于 流 的 重 定向 。 比 如 ， 把 flag 设 为 UV_INHERIT_STREAM ， 
然后 再 设置 父 进 程 中 的 data stream ， 这 时 子 进程 只 会 把 这 个 stream 当 成 是 标准 
的 MO。 这 可 以 用 来 实现 ， 例 如 CGI ° 


一 个 简单 的 CGI 脚本 的 例子 如 下 : 


cgiltick.c 


#include <stdio.h> 
#include <unistd.h> 


int main() í 
WE Le 
fon (L = eh Ee E 
BEZE tickNmn 
fflush(stdout); 
sleep(1); 


} 
printf("BOOM!Nn"); 
return 0; 


CGI 服务 器 用 到 了 这 章 和 网 络 那 章 的 知识 ， 所 以 每 一 个 client 在 中 断 连 接 后 ， 都 会 被 
发 送 10 个 tick。 


cgi/main.c 


void on new connection(uv_stream t *server, int status) í 


if (status == -1) { 
// error! 
return; 

} 


uv_tcp_t *client = (uv tcp t*) malloc(sizeof(uv tcp t)); 

uv_tcp_init(loop, client); 

if (uv_accept(server, (uv_stream_t*) client) == 0) í 
invoke_cgi_script(client); 


else { 
uv_close((uv_handle_t*) client, NULL); 
} 


上 述 代码 中 ， 我 们 接受 了 连接 ， 并 把 Socket CA) 传递 给 invoke cgi script ° 


cgi/main.c 


args[1] = NULL; 
/* ... finding the executable path and setting up arguments 


options.stdio_count = 3; 

uv_stdio_container_t child _stdio[3]; 
child_stdio[0].flags = UV_IGNORE; 

child _stdio[1].flags = UV_INHERIT_ STREAM; 
child_stdio[1].data.stream = (uv_stream_t*) client; 
child_stdio[2].flags = UV_IGNORE; 

options.stdio = child_stdio; 


options.exit_cb = cleanup_handles; 
options.file = args[0]; 
options.args = args; 


M Set this so we cannelosenthnensocKkerafter Ene rehi TARPrOcCeEsSsS 

child_req.data = (void*) client; 

UME E 

if ((r = uv_spawn(loop, &child_req, &options))) { 
fprintf(stderr, "%s\n", uv_strerror(r)); 


UE 





cgi 的 stdout 被 绑 定 到 Socket 上 ， 所 以 无 论 tick 脚 本 程序 打印 什么 ， 都 会 发 送 到 
Clients: E ， 我 们 能 够 很 好 地 处 理 读 写 并 发 操作 ， 而 且 用 起 来 也 很 方 


便 。 但 是 要 记得 这 么 做 ， 是 很 浪费 资源 的 。 

Pipes 

libuv 的 uv_pipe_t 结构 可 能 会 让 一 些 unix 程 序 员 产生 困惑 ， 因 为 它 像 魔术 般 交 幻 

出 | 和 pipe(7) ° 但 这 里 的 —pipe_t 并 不 是 IPC 机 制 里 的 匿名 管道 (在 IPC 

里 ， ' pipe EA 多 道 ， 只 允许 父子 进程 之 间 通 信 。FIFO 则 允许 没有 亲 威 关系 的 进程 


间 通 信 ， 显 然 |ibuv 里 的 uv. Se t 不 是 第 一 种 ) ° uv t 背后 有 unix 本 地 
echt windows g: 22 E: 道 的 支持 ， 可 以 实现 多 进程 间 的 通信 。 下 面 会 具体 讨 


论 。 


Parent-child IPC 


父 进程 与 子 进 程 可 以 通过 单 工 或 者 双 工 管道 通信 ， 获 得 管道 可 以 通过 设 

Ë uv_stdio_container_t.flags 为 UV_CREATE_PIPE ， UV_READABLE_PIPE 
或 者 UV_WRITABLE_PIPE 的 按 位 或 的 值 。 上 述 的 读 写 标记 是 对 于 子 进程 而 言 
的 。 


Arbitrary process IPC 


既然 本 地 socket 具 有 确定 的 名 称 ， 而 且 是 以 文件 系统 上 的 位 置 来 标示 的 (例如 ， 
unix 中 socket 是 文件 的 一 种 存在 形式 ) ， 那 么 它 就 可 以 用 来 在 不 相关 的 进程 间 完 成 
通信 任务 。 被 开源 桌面 环境 使 用 的 D-BUS 系统 也 是 使 用 了 本 地 socket 来 作为 事件 
通知 的 ， 例 如 ， 当 消息 来 到 ， 或 者 检测 到 硬件 的 时 候 ， 各 种 应 用 程序 会 被 通知 到 。 
mysql 服 务 器 也 运行 着 一 个 本 地 socket， 等 待 客户 端的 访问 。 


当 使 用 本 地 socket 的 时 候 ， 客 户 端 服 务 器 模型 通常 和 之 前 类 似 。 在 完成 初始 化 
后 ， 发 送 和 接受 消息 的 方法 和 之 前 的 tcp 类 似 ， 接 下 来 我 们 同样 适用 echo 服 务 器 的 
例子 来 说 明 。 


pipe-echo-server/main.c 


int main() { 
loop = uv_default loop(); 


uv_pipe_t Server: 
uv_pipe_ init(loop, &server, 0); 


signal(SIGINT, remove_ sock); 


INE Tes 

if ((r = uv_pipe bind(&server, "echo.sock"))) { 
fprintf(stderr, "Bind error %sNn", uv_err_name(r)); 
return T 


if ((r = uv_listen((uv_stream_t*) &server, 128, on_new_connect: 
fprintf(stderr, "Listen error %s\n", uv_err_name(r)); 
retuUnnT2> 


} 
return uv_run(loop, UV_RUN_DEFAULT); 





我 们 把 socket 命 名 为 echo.sock， 意 味 着 它 将 会 在 本 地 文件 夹 中 被 创造 。 对 于 
stream API 来 说 ， 本 地 socekt 表 现 得 和 tcp 的 socket 差 不 多 。 你 可 以 使 用 Socat 测 试 
一 下 服务 器 : 


$ Socat - /path/to/socket 
客户 端 如 果 想 要 和 服务 器 端 连接 的 话 ， 应 该 使 用 : 


void uv_pipe_connect(uv_connect_t *req, uv_pipe_t *handle, const cl 


al SSC 








上 述 函 数 ，name 应 该 为 echo.sock。 


Sending file descriptors over pipes 


最 酷 的 事情 是 本 地 socket 可 以 传递 文件 描述 符 ， 也 就 是 说 进程 间 可 以 交换 文件 描述 
符 。 这 样 就 允许 进程 将 它们 的 MO 传递 给 其 他 进程 。 它 的 应 用 场景 包括 ， 负 载 均 衡 服 
务 器 ， 分 派 工作 进程 等 ， 各 种 可 以 使 得 cpu 使 用 最 优化 的 应 用 。libuv 当 前 只 支持 通 

过 管道 传输 TCP sockets 或 者 其 他 的 pipes ° 
为 


D 


mt 


了 展示 这 个 功能 ， 我 们 将 来 实现 一 个 由 循环 中 的 工人 进程 处 理 client 端 请 求 ， 的 这 
么 一 个 echo 服 务 器 程序 。 这 个 程序 有 一 些 复杂 ， 在 教程 中 只 截取 了 部 分 的 片段 ， 为 
了 更 好 地 理解 ， 我 推荐 你 去 读 下 完整 的 代码 。 


人 进程 很 简单 ， 文 件 描 述 符 将 从 主 进程 传递 给 它 。 
multi-echo-server/worker.c 


uv_loop_t *loop; 
uv_pipe_t queue; 
E masmi mt 
loop = uv_default_loop(); 


uv_pipe_init(loop, &queue, 1 /* ipc */); 

uv_pipe_open(&queue, 0); 

uv_read_start((uv stream t*)&queue, alloc_buffer, on. new Conner 
return uv_run(loop, UV_RUN_DEFAULT); 





queue 是 另 一 端 连接 上 主 进程 的 管道 ， 因 此 ， 文 件 描 述 符 可 以 传送 过 来 。 
在 uv_pipe_init 中 将 ipc 参数 设置 为 1 很 关键 ， 因 为 它 标 明了 这 个 管道 将 被 用 
来 做 进程 间 通 信 。 因 为 主 进程 需 要 把 文件 handle 赋 给 了 工人 进程 作为 标准 输入 ， 
此 我 们 使 用 uv_pipe_open 把 stdin 作 为 pipe〈 别 忘 了 ，0 代 表 stdin ) ° 


multi-echo-server/worker.c 


void on new connection(uv_ stream t "o, ssize t nread const uv buf 
if (nread < 0) í 
If (nread != UV_EOF) 
fprintf(stderr, "Read error %sNn", uv_err_name(nread)), 
uv_close((uv_handle_t*) q, NULL); 
return; 


} 


uv_pipe_t *pipe = (uv_pipe_t*) q; 

if (!uv_pipe_pending_count(pipe)) { 
fprintf(stderr, "No pending countNmn"); 
return; 


} 


uv_handle_type pending = uv_pipe_pending_type(pipe); 
assert(pending == UV_TCP); 


uv_tcp_t *client = (uv_tcp_t*) malloc(sizeof(uv_tcp_t)); 
uv_tcp_init(loop, client); 
if (uv_accept(q, (uv_stream_t*) client) == 0) { 
uv_os fd t fd; 
uv_fileno((const uv_handle t*) client, &fd); 
fprintf(stderr, "Worker %d: Accepted fd %d\n", getpid(), fí 
uv_read_start((uv stream t*) client, alloc_buffer, echo re 


} 
else í 
uv_close((uv_handle_t*) client, NULL); 





首先 ， 我 们 调用 uv pipe pending count 来 确定 从 handle 中 可 以 读 取出 数据 。 如 
果 你 的 程序 能 够 处 理 不 同类 型 的 handle， 这 时 uv_pipe pending type 就 可 以 用 
来 决定 当前 的 闫 型 。 虽 然 在 这 里 使 用 accept 看 起 来 很 怪 ， 但 实际 上 是 讲 得 通 
的 。 accept 最 常见 的 用 途 是 从 其 他 的 文件 描述 符 (监听 的 socket) 获取 文件 描述 
符 (client 端 ) 。 这 从 原理 上 说 ， 和 我 们 现在 要 做 的 是 一 样 的 : 从 queue 中 获取 文件 
描述 符 (client) 。 接 下 来 ，Worker 可 以 执行 标准 的 echo 服 务 器 的 工作 了 。 


我 们 再 来 看 看 主 进程 ， 观 察 如 何 尼 动 Worker 来 达到 负载 均衡 。 
multi-echo-server/main.c 


struct child worker í 
uv_process_t req; 
uv_process_options_t options; 
uv_pipe_t pipe; 

} *workers; 


child worker 结构 包 庄 着 进程 ， 和 连接 主 进程 和 各 个 独立 进程 的 管道 。 
multi-echo-server/main.c 


void setup_workers() { 
round_robin_counter = 0; 


Z 


// launch same number of workers as number of CPUs 
IV e pe ge E t Trio; 

int cpu_count; 

uv_cpu_info(&info, &cpu_count); 
uv_free_cpu_info(info, cpu_count); 


child_worker_count = cpu_count; 


workers = calloc(sizeof(struct child_worker), cpu_count); 
while (cpu_count--) í 
struct child_worker *worker = &workers[cpu_count]; 
uv_pipe_init(loop, &worker->pipe, 1); 


uv_stdio_container_t child _stdio[3]; 

child stdio[0].flags = UV_CREATE_PIPE | UV_READABLE PIPE; 
child_stdio[0].data.stream = (uv stream t*) &worker->pipe; 
child_stdio[1].flags = UV_IGNORE; 

child stdio[2] .flags = UV_INHERIT_FD; 

child stdio[2].data.fd = 2; 


worker->options.stdio = child_stdio; 
worker->options.stdio_count = 3; 


worker->options.exit_cb = close_process_handle; 
worker->options.file args[0]; 
worker->options.args args; 


uv_spawn(loop, &worker->req, &worker->options); 
fprintf(stderr, "Started worker %d\n", worker->req.pid); 


} 
二 | 


首先 ， 我 们 使 用 酷 炉 的 uv_cpu_info 驾 数 获取 到 当前 的 cpu 的 核心 个 数 ， 所 以 我 

们 也 能 启动 一 样 数目 的 worker 进 程 。 再 次 强调 一 下 ， 务 必 将 uv_pipe_init 的 ipc 
参数 设置 为 1°。 接 下 来 ， 我 们 指定 子 进程 的 stdin 是 一 个 可 读 的 管道 (从 子 进 程 的 
角度 来 说 ) 。 接 下 来 的 一 切 就 很 直观 了 ，worker 进 程 被 启动 ， 等 待 着 文件 描述 符 被 
写 入 到 他 们 的 标准 输入 中 。 


在 主 进程 的 on_new_connection 中 ， 我 们 接收 了 client 端 的 Socket， 然 后 把 它 传递 
给 worker 环 中 的 下 一 个 可 用 的 worker 进 程 。 


multi-echo-server/main.c 


void on new connection(uv stream t "server, int status) { 


if (status == -1) í 
// error! 
return; 

} 


üv tcp t “client = (uv tcp t*) malloc(sizeof(uv_ tep t)); 
uv_tcp_init(loop, client); 
if (uv_accept(server, (uv_stream_t*) client) == 0) { 


uv_write_t *write_req = (uv_write_t*) malloc(sizeof(uv_wril 
dummy_buf = uv_buf_init("a", 1); 

struct child_worker *worker = &workers[round robin_counter 
uv_write2(write_req, (uv _ stream t*) &worker->pipe，&dummy 上 
round_robin_counter = (round robin counter + 1) % child wo 


} 
else í 

uv_close((uv_handle_t*) client, NULL); 
} 





uv_write2 能 够 在 所 有 的 情形 上 做 了 一 个 很 好 的 抽象 ， 我 们 只 需要 将 client 作 为 一 
个 参数 即 可 完成 传输 。 现 在 ， 我 们 的 多 进程 echo 服 务 器 已 经 可 以 运转 起 来 啦 。 


感谢 Kyle 指 出 了 uv_write2 需要 一 个 不 为 空 的 buffer ° 


Advanced event loops 


libuv 提 供 非常 多 的 控制 event-loop 的 方法 ， 你 能 通过 使 用 多 loop 来 实现 很 多 有 趣 
的 功能 。 你 还 可 以 将 libuv 的 event loop 嵌 入 到 其 它 基 于 event-loop 的 库 中 。 比 如 ， 想 
ee A E 


务 。 


Stopping an event loop 


uv_stop() 用 来 终止 event loop。 loop 会 停止 的 最 早 时 间 点 是 在 下 次 循环 的 时 候 ， 
或 者 稍 晚 些 的 时 候 。 这 也 就 意味 着 在 本 次 循环 中 已 经 准备 被 处 理 的 事件 ， 依 然 会 被 
处 理 ， uv_stop 不 会 起 到 作用 。 当 uv_stop 被 调用 ， 在 当前 的 循环 中 ，loop 不 
会 被 | 操作 阻塞 。 上 面 这 些 说 得 有 点 玄 乎 ， 还 是 让 我 们 看 下 uv_run() 的 代码 : 


srclunixlcore.c - uv_run 


int uv_run(uv_loop_t* loop, uv run mode mode) í 
int timeout; 
amu Tee 


int ran_pending; 


r = uv loop_alive(loop); 
o (ir? 
uv update time(loop); 


while (r != © && loop->stop_flag == 0) { 
uv_update_time(loop); 
uv run_timers(loop); 
ran_pending = uv_run_pending(loop); 
uv_run_idle(loop); 
uv_run_prepare(loop); 


timeout = 0; 
if ((mode == UV_RUN_ONCE Së !ran_pending) || mode == UN RUN DÉI 
timeout = uv_backend_timeout(loop); 


uv_io_poll(loop, timeout); 


BIE 





stop_flag 由 uv_stop Ë ° IA PA libuv €H h 28 Æ —kloopt s T 
被 调用 的 ， 因 此 调用 uv stop 并 不 能 中 止 本 次 循环 。 首 先 ，libuv 会 更 新 定时 器 ° 
然后 运行 接 下 来 的 定时 器 ， 空 转 和 准备 回调 ， 调 用 任何 准备 好 的 ID 回调 函数 。 如 果 
你 在 它们 之 间 的 任何 一 个 时 间 里 ， 调 用 uv_stop() ， stop flag 会 被 设置 为 1。 


这 会 导致 uv_backend_timeout() 返回 0， 这 也 就 是 为 什么 loop 不 会 阻塞 在 LO 
上 。 从 另外 的 角度 来 说 ， 你 在 任何 一 个 检查 handler 中 调用 uv_stop ， 此 时 |/O 已 
经 完成 ， 所 以 也 没有 影响 。 


在 已 经 得 到 结果 ， 或 是 发 生 错误 的 时 候 ， uv_stop() 可 以 用 来 关闭 一 个 loop， 而 
且 不 需要 保证 handler 停 止 的 顺序 。 


下 面 是 一 个 简单 的 例子 ， 它 演示 了 loop 的 停止 ， 以 及 当前 的 循环 依旧 在 执行 。 
uvstop/main.c 
#include <stdio.h> 
#include <uv.h> 
int64 t counter = 0; 
void idle cb(uv_ idle t *handle) í 
printf("Idle callbackNn"); 
counter++; 
if (counter >= 5) í 


uv_stop(uv_default_loop()); 
printf (tuv stop() calledNn"”); 


} 
void prep cb(uv_prepare t *handle) { 


printf("Prep callbackNn"); 


ime man) 
uv_idle_t idler; 
uv_prepare_t prep; 


uv_idle_init(uv_default_loop(), &idler); 
uv_idle_start(&idler, idle_cb); 


uv_prepare_init(uv_default_loop(), &prep); 
uv_prepare_start(&prep, prep_cb); 


uv_run(uv_default_loop(), UV_RUN_DEFAULT); 


return 0; 


Utilities 


本 章 介 绍 的 工具 和 技术 对 于 常见 的 任务 非常 的 实用 。libuv 吸 收 了 libev 用 户 手 册页 中 
所 涵盖 的 一 些 模式 ， 并 在 此 基础 上 对 API 做 了 少许 的 改动 。 本 章 还 包含 了 一 些 无 需 


用 完整 的 一 章 来 介绍 的 libuv API ° 


Timers 


在 定时 器 启动 后 的 特定 时 间 后 ， 定 时 器 会 调用 回调 函数 。libuv 的 定时 器 还 
为 ， ， 按 时间 间隔 定时 启动 ， 而 不 是 只 启动 一 次 。 


可 以 简单 地 使 用 超时 时 间 timeout 作为 参数 初始 化 一 个 定时 器 ， 还 有 一 个 可 选 参 


数 repeat 。 定 时 器 能 在 任何 时 间 被 终止 。 


uv_timer_t timer_req; 


uv_timer_init(loop, &timer_req); 
uv_timer_start(&timer_req, callback, 5000, 2000); 


上 述 操作 会 启动 一 个 循环 定时 器 (repeating timer) ， 它 会 在 调 


用 uv_timer_start 后 ，5 秒 (timeout) 启动 回调 函数 ， 然 后 每 隔 2 秒 (repeat) 


循环 启动 回调 函数 。 你 可 以 使 用 : 


uv_timer_stop(&timer_req); 


来 停止 定时 器 。 这 个 函数 也 可 以 在 回调 函数 中 安全 地 使 用 。 
循环 的 间隔 也 可 以 随时 定义 ， 使 用 : 


uv_timer_set_repeat(uv_timer_t *timer, int64 t repeat); 


它 会 在 可 能 的 时 候 发 挥 作用 。 如 果 上 述 函 数 是 在 定时 器 回调 沟 数 中 调用 的 ， 
着 : 
e 如 果 定 时 器 未 设置 为 循环 ， 这 意味 着 定时 器 已 经 停止 。 需 要 先 
用 uv_ timer start 重新 启动 。 
e 如 果 定 时 器 被 设置 为 循环 ， 那 么 下 一 次 超时 的 时 间 已 经 被 规划 好 了 ， 所 以 
在 切换 到 新 的 间隔 之 前 ， 旧 的 间隔 还 会 发 挥 一 次 作用 。 
SEA 


int uv _ timer again(uv timer t *) 


意味 


只 适用 于 循环 定时 器 ， 相 当 于 停止 定时 器 ， 然 后 把 原先 的 timeout 和 repeat 什 
都 设置 为 之 前 的 repeat 值 ， 启 动 定时 器 。 如 果 当 该 函数 调用 时 ， 定 时 器 未 启动 ， 
则 调用 失败 (错误 码 为 UV_EINVAL ) 并 且 返 回 一 1。 


下 面 的 一 节 会 出 现 使 用 定时 器 的 例子 。 


Event loop reference count 


event-loop 在 没有 了 活跃 的 handle 之 后 ， 便 会 终止 。 整 套 系 统 的 工作 方式 是 : 在 
handle 增 加 时 ，event- GE ， 在 handle 停 止 时 ， 引 用 计数 减少 1。 当 
然 ，libuv 也 允许 手动 地 更 改 引 用 计数 ， 通 过 使 用 : 


void uv_r SE handle t*); 
void uv _unref(uv handle t*); 


这 样 ， 就 可 以 达到 允许 loop 即 使 在 有 正在 洛 动 的 定时 器 时 ， 仍 然 能 够 推出 。 或 者 是 
使 用 自 定义 的 uv_handle_t 对 象 来 使 得 loop 保 持 工 作 。 


第 二 个 函数 可 以 和 间隔 循环 定时 器 结合 使 用 。 。 你 会 有 一 个 每 隔 X 秒 执行 一 次 的 垃圾 
— ， 或 者 是 你 的 网 络 服务 器 会 每 隔 一 段 时 间 向 其 他 人 发 送 一 次 心跳 信号 ， 但 是 

WEE 
Ge? e EEN 终止 程序 。 这 时 你 就 可 以 立即 unref 定 时 器 ， 即 便 定 时 器 这 时 是 
GE 于 的 监视 器 ， 你 依旧 可 以 停止 uv_run() ° 


它们 同样 会 出 现在 node.js 中 ， 如 js 的 APIl 中 封装 的 libuv 方 法 。 每 一 个 js 的 对 象 产 生 一 
个 uv handle t (所 有 监视 器 的 超 类 ) ， 同 样 可 以 被 uv_ref 和 uv_unref。 


ref-timer/main.c 


uv_loop_t *loop; 
uv_timer_t gc_req; 
uv_timer_t fake "ob reg: 


Int main) A 
loop = uv_default loop(); 


uv_timer_init(loop, &gc_req); 
uv_unref((uv_handle t*) &gc_req); 


uv_timer_start(&gc_req, gc, ©, 2000); 


// could actually be a TCP download or something 
uv_timer_init(loop, &fake job_req); 
uv_timer_start(&fake job_req, fake job, 9000, 0); 
return uv_run(loop, UV_RUN_DEFAULT); 


首先 初始 化 垃圾 回收 器 的 定时 器 SS: 然后 在 立刻 unref © œ 注意 观察 9 秒 之 后 ， 此 时 
fake_job 完 成， 程序 会 自动 退出 ， 即 使 垃圾 回收 器 还 在 运行 。 


Idler pattern 


空转 的 回调 函数 会 在 每 一 次 的 event-loop 循 环 激发 一 次 。 空 转 的 回调 函数 可 以 用 来 
执行 一 些 优 先 级 较 低 的 活动 。 比 如 ， 你 可 以 向 开发 者 发 送 应 用 程序 的 每 日 性 能 表现 
情况 ， 以 便于 分 析 ， 或 者 是 使 用 用 户 应 用 cpu 时 间 来 做 SETI 运 算 :)。 空 转 程 序 还 可 
以 用 于 GUI 应 用 。 比 如 你 在 使 用 event-loop 来 下 载 文件 ， Be 
前 并 没有 其 他 的 事件 ， 则 你 的 event-loop 会 阻塞 ， 这 也 就 意味 着 你 的 下 载 进度 条 
停滞 ， 用 户 会 面 对 一 个 无 响应 的 程序 。 面 对 这 种 情况 ， 空 转 监 视 u 
作 。 


idle-compute/main.c 


uv_loop_t *loop; 

uv fs t stdin_watcher; 
uv_idle t idler; 

char buffer[1024]; 


int main() { 
loop = uv_default loop(); 


uv_idle init(loop, &idler); 


uv_buf_t buf = uv_buf_init(buffer, 1024); 

uv_fs_read(loop, &stdin watcher, ©, &buf, 1, -1, on_type); 
uv_idle start(&idler, crunch_away); 

return uv_run(loop, UV_RUN_DEFAULT); 


上 述 程序 中 ， 我 们 将 空转 监视 器 和 我 们 真正 关心 的 事件 排 在 一 
起 。 crunch_away EE 直到 输入 字符 并 回 车 。 然 后 程序 会 被 中 断 很 
短 的 时 间 ， 用 来 处 理 数据 读 取 ， 然 后 在 接着 调用 空转 的 回调 函数 。 


idle-compute/main.c 


void Crunch away(uv idle t* handle) í 
// Compute extra-terrestrial life 
// fold proteins 
// computer another digit of PI 
Z or Similar 
fprintf(stderr, <cCompüting PI Nn 
// just to avoid overwhelming your terminal emulator 
uv_idle_stop(handle); 


Passing data to worker thread 


在 使 用 uv_queue work 的 时 候 ， 你 通常 需要 给 工作 线程 传递 复杂 的 数据 。 解 决 方 
案 是 自 定义 struct， 然 后 使 用 uv_work_t.data 指向 它 。 一 个 稍微 的 不 同 是 必须 

让 uv_work t 作为 这 个 自 定 义 struct 的 成 员 之 一 《把 这 叫做 接力 棒 ) 。 这 么 做 就 可 
以 使 得 ， 同 时 回收 数据 和 uv_wortk_t ° 


Struct ftp_baton í 
uv_work_t reg: 
char *host; 
int port; 
char *username; 
char *password; 


ftp_baton *baton = (ftp_baton*) malloc(sizeof(ftp_baton)); 
baton->req.data = (void*) baton; 

baton->host = strdup("my.webhost.com"); 

baton->port = 21; 

EC 


uv Oueue work loop, &baton->req, TCp Session, ftp_cleanup); 


现在 我 们 创建 完了 接力 棒 ， 并 把 它 排 入 了 队列 中 。 
现在 就 可 以 随 性 所 谷地 获取 自己 想 要 的 数据 啦 。 


void ftp_ session(uv work C *req) { 
ftp_baton *baton = (ftp_baton*) redq->data 


fprintf(stderr, "Connecting to %sNn", baton->host); 


void ftp cleanup(uv work t *req) { 
ftp_baton *baton = (ftp_baton*) req->data; 


free(baton->host); 


Z 
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free(baton); 


我 们 既 回 收 了 接力 棒 ， 同 时 也 回收 了 监视 器 。 


External UO with polling 


通常 在 使 用 第 三 方 库 的 时 候 ， 需 要 应 对 他 们 自己 的 ID， 还 有 保持 监视 他 们 的 socket 
和 内 部 文件 。 在 此 情形 下 ， 不 可 能 使 用 标准 的 ID 流 操 作 ， 但 第 三 方 库 仍 然 能 整合 进 
event-loop 中 。 所 有 这 些 需要 的 就 是 ， 第 三 方 库 就 必须 允许 你 访问 它 的 底层 文件 描 
述 符 ， 并 且 提 供 可 以 处 理 有 用 户 定义 的 细微 任务 的 函数 。 但 是 一 些 第 三 库 并 不 允许 
你 这 么 做 ， 他 们 只 提供 了 一 个 标准 的 阻塞 ID 函数， 此 函数 会 完成 所 有 的 工作 并 返 
回 。 在 event-loop 的 线程 直接 使 用 它们 是 不 明智 的 ， 而 是 应 该 使 用 libuv 的 工作 线 
程 。 当 然 ， 这 也 意味 着 失去 了 对 第 三 方 库 的 颗粒 化 控制 。 

libuv 的 uv poll 简单 地 监视 了 使 用 了 操作 系统 的 监控 机 制 的 文件 描述 符 。 从 某 方 
面 说 ，libuv 实 现 的 所 有 的 ID 操作 ， 的 背后 均 有 uv_poll 的 支持 。 无 论 操作 系统 何 
时 监视 到 文件 描述 符 的 改变 ，libuv 都 会 调用 响应 的 回调 函数 。 

现在 我 们 简单 地 实现 一 个 下 载 管理 程序 ， 它 会 通过 libcurl 来 下 载 文件 。 我 们 不 会 直 
接 控 制 libcurl， 而 是 使 用 libuv 的 event-loop， 通 过 非 阻塞 的 异步 的 乡 重 接口 来 处 理 下 
载 ， 与 此 同时 ，libuv 会 监控 ID 的 就 绪 状 态 。 


uvwget/main.c - The setup 


#include <assert.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <uv.h> 
#include <curl/curl.h> 


uv_loop_t *loop; 
CURLM *curl_handle; 
uv_timer_t timeout; 


} 


ime main(int arge Char argy) ti 


loop = uv_default_loop(); 


if (argc <= 1) 
returnos 


if (curl_global_init(CURL_GLOBAL_ALL)) { 
printi (stederr E EEN init URENn 
euma p 


} 
uv_timer_init(loop, &timeout); 


curl_handle = curl multi init(); 
curl] multi setopt(curl handle, CURLMOPT_SOCKETFUNCTION, handle 
curl multi setopt(curl] handle, CURLMOPT_TIMERFUNCTION, start E: 


while (argc-- > 1) í 
add _download(arov[argc], argc); 
} 


uv_run(loop, UV_RUN_DEFAULT); 
curl multi cleanup(curl handle); 
return oF 





每 种 库 整合 进 libuv 的 方式 都 是 不 同 的 。 以 libcurl 的 例子 来 说 ， 我 们 注册 了 两 个 回调 
žr o socket A Až handle socket 会 在 socket 状态 改变 的 时 候 被 触发 ， 因 此 
我 们 不 得 不 开始 轮 询 它 。 start_timeout 是 libcurl 用 来 告知 我 们 下 一 次 的 超时 间 
隔 的 ， 之 后 我 们 就 应 该 不 管 当 前 ID 状态 ， 驱 动 libcurl 向 前 。 这 些 也 就 是 libcurl 能 处 理 
错误 或 驱动 下 载 进度 向 前 的 原因 。 


可 以 这 么 调用 下 载 器 : 


$ ./uvwget Turi! [ur12] 


我 们 可 以 把 ur| 当 成 参数 传 入 程序 。 


uvwget/main.c - Adding urls 


void add_download(const char *url, int num) í 
char filename[50]; 
sprintf(filename, "od. download", num); 
FILE *file; 


file = fopen(filename, "wii: 

if (file == NULL) í 
fprintf(stderr, "Error opening %sNn", filename); 
return; 


} 


CURL *handle = curl_easy_init(); 

curl_easy_setopt(handle, CURLOPT_WRITEDATA, file); 
curl_easy_setopt(handle, CURLOPT_URL, url); 
curl_multi_add_handle(curl_handle, handle); 

fprintf(stderr, "Added download %s -> %s\n", url, filename); 


我 们 允许 libcurl 直 接 向 文件 写 入 数据 。 


start_timeout 会 被 libcurl 立 即 调用 。 它 会 启动 一 个 libuv 的 定时 器 ， 使 

用 CURL_SOCKET_TIMEOUT 驱动 curl multi socket_action ， 当 其 超时 时 ， 调 
用 它 。 curl multi socket action 会 驱动 libcurl|， 也 会 在 socket 状 态 改变 的 时 候 
被 调用 。 但 在 我 们 深入 讲解 它 之 前 ， 我 们 需要 轮 询 监听 socket， 等 

待 handle_socket 被 调用 。 


uvwget/main.c - Setting up polling 


void start timeout(CURLM *multi, long timeout ms, void *userp) í 
If (timeout_ms <= 0) 
timeout ms = 1: /* © means directly call socket_action, bul 
uv_timer_start(&timeout, on_timeout, timeout_ms, 0); 


} 


int handle socket (CURL "easy, curl socket t s, int action, void Zu: 
curl_context_t *curl_context; 
if (action == CURL_POLL_IN || action == CURL_POLL_OUT) { 
if (socketp) { 
curl_context = (curl_context_t*) socketp; 


} 
else í 
curl_context = create_curl_context(s); 
curl_multi_assign(curl_handle, s, (void *) curl Contes 
} 


} 


switch (action) { 
case CURL_POLL_IN: 
uv Doll start(&curl context->poll] handle, UV_READABLE, 
break; 
case CURL_ POLL OUT: 
uv Doll start(&curl context->poll] handle, UV_WRITABLE, 
break; 
case CURL_POLL_REMOVE : 
if (Socketp) { 
uv_poll_stop(&((curl context t*)socketp)->poll_hant 
destroy_curl_context((curl_context_t*) socketp); 
curl_multi_assign(curl_handle, s, NULL); 


} 
break; 
default: 
abortii: 
} 
petunio 


EE 


我 们 关心 的 是 Socket 的 文件 描述 符 S， 还 有 action。 对 应 每 一 个 socket， 我 们 都 创造 
了 uv_poll t ， 并 用 curl multi assign 把 它们 关联 起 来 。 每 当 回 调 函 数 被 调 
用 时 ， socketp 都 会 指向 它 。 


在 下 载 完成 或 失败 后 ，libcurl 需 要 移 除 poll。 所 以 我 们 停止 并 回收 了 poll 的 handle ° 


我 们 使 用 UV_READABLE 或 UV WRITABLE 开始 轮 询 ， 基 于 libcurl 想 要 监视 的 事 

件 。 当 Socket 已 经 准备 好 读 或 写 后 ，libuv 会 调用 轮 询 的 回调 函数 。 在 相同 的 handle 
上 调用 多 次 uv_poll_start 是 被 允许 的 ， 这 么 做 可 以 更 新 事件 的 参 

数 。 curl_perform 是 整个 程序 的 关键 。 





uvwget/main.c - Driving libcurl. 


void curl_perform(uv_poll_t *req, int status, int events) { 
uv_timer_stop(&timeout); 
int running_handles; 
int flags = 0; 
if (status < 0) flags = CURL_CSELECT ERR: 
if (!status Së events & UV_READABLE) flags |= CURL_CSELECT IN; 
if (!status Së events & UV_WRITABLE) flags |= CURL_CSELECT_ OUT, 


curl_context_t *context; 
context = (curl_context_t*)req; 


curl_multi_socket_action(curl_handle, context->sockfd, flags, «é 
check_multi_info(); 


Ki — 


首先 我 们 要 做 的 是 停止 定时 器 ， 因 为 内 部 还 有 其 他 要 做 的 事 。 接 下 来 我 们 我 们 依据 
触发 回调 函数 的 事件 ， 来 设置 fag。 然 后 ， 我 们 使 用 上 述 socket 和 flag 作 为 参数 ， 来 
调用 curl multi socket action 。 在 此 刻 libcurl 会 在 内 部 完成 所 有 的 工作 ， 然 

后 尽快 地 返回 事件 驱动 程序 在 主线 程 中 急需 的 数据 。libcurl 会 在 自己 的 队列 中 将 传 

输 进 度 的 消息 排队 。 对 于 我 们 来 说 ， 我 们 只 关心 是 否 传输 完成 ， 这 类 消息 。 所 以 我 
们 将 这 类 消息 提取 出 来 ， 并 将 传输 完成 的 handle 回 收 。 





uvwget/main.c - Reading transfer status. 


void check multi info(void) í 
char *done url; 
CURLMsg *message; 
int pending; 


while ((message = curl_multi_info_read(curl_handle, &pending)). 
switch (message->msg) í 
case CURLMSG_DONE: 
curl_easy_getinfo(message->easy_handle, CURLINFO_EFFEC` 
&done_ur1); 
printf("%s DONENn", done url); 


curl_multi_remove_handle(curl_handle, message->easy_har 
curl easy_ cleanup(message->easy_handle); 
break; 


default: 


fprintf(stderr, "CURLMSG defaultNn"): 
abort O 





Loading libraries 


libuv 提 供 了 一 个 跨 平 台 的 API 来 加 载 共 享 库 shared libraries。 这 就 可 以 用 来 实现 你 
自己 的 插件 一 扩展 一 模块 系统 ， 它们 可 以 被 nodejs 通 过 require() 调用 。 只 要 你 
的 库 输 出 的 是 正确 的 符号 ， 用 起 来 还 是 很 简单 的 。 在 载 入 第 三 方 库 的 时 候 ， ， 要 注意 
错误 和 安全 检查 ， 和 否则 你 的 程序 就 会 表现 出 不 可 预测 的 行为 。 下 面 这 个 例子 实现 了 
一 个 简单 的 播 件 ， 它 只 是 打印 出 了 自己 的 名 字 。 


首先 看 下 提供 给 插件 作者 的 接口 。 
plugin/plugin.h 
#ifndef UVBOOK_PLUGIN_SYSTEM 
#define UVBOOK_PLUGIN_SYSTEM 


// Plugin authors should use this to register their plugins with ml 
void mfp_register(const char *name); 


#endif 
Bl 2 








你 可 以 在 你 的 程序 中 给 插件 添加 更 多 有 用 的 功能 (mfp is My Fancy Plugin) 。 使 用 
了 这 个 api 的 插件 的 例子 : 


plugin/hello.c 


#include "plugin.h" 


void initialize() í 
mfp_register("Hello World!"); 


我 们 的 接口 定义 了 ， 所 有 的 插件 都 应 该 有 一 个 能 被 程序 调用 的 initialize í 
数 。 这 个 插件 被 编译 成 了 共享 库 ， 因 此 可 以 被 我 们 的 程序 在 运行 的 时 候 载 入 。 


$ ./plugin libhello.dylib 
Loading libhello.dylib 
Registered plugin "Hello World!" 


Note 

共享 库 的 后 级 名 在 不 同 平台 上 是 不 一 样 的 。 在 Linux 上 是 libhello.so。 
使 用 uv_dlopen 首先 载 入 了 共享 库 libhello.dylib 。 再 使 用 uv_dlsym 获取 
了 该 插件 的 initialize 函数 ， 最 后 在 调用 它 。 


plugin/main.c 


#include "plugin.h" 
typedef void (“init plugin function)(); 


void mfp_register(const char *name) { 
fprintf(stderr, "Registered plugin \"%s\"\n", name); 
} 


See ua (aint e geleet eeh deele E 
if (argc == 1) í 
fprintf(stderr, "Usage: %s [plugini] [plugin2] ...Nn", argi 
return 0; 


} 


úv laib e I (Uv lab ti) malloc(sizeof (Uv Dh: 
while (--argc) { 
fprintf(stderr, "Loading %s\n", argv[argc]); 
if (uv_dlopen(argv[argc], lib)) í 
fprintf(stderr, "Error: %s\n", uv_dlerror(lib)); 
continue; 


} 


init_plugin_function init_plugin; 
if (uv_dlsym(lib, "initialize", (void **) &init_plugin)) { 
fprintf(stderr, "dlsym error: %s\n", uv_dlerror(lib)); 


continue; 
} 
init_plugin(); 
} 
return 0; 


El 


函数 uv_dlopen 需要 传 入 一 个 共享 库 的 路 径 作为 参数 。 当 它 成 功 时 返回 0， 出 错 
时 返回 一 1°。 使 用 uv_dlerror 可 以 获取 出 错 的 消息 。 


uv_dlsym 的 第 三 个 参数 保存 了 一 个 指向 第 二 个 参数 所 保存 的 函数 的 指 
针 。 init plugin function 是 一 个 函数 的 指针 ， 它 指向 了 我 们 所 需要 的 程序 插 
件 的 函数 。 





TTY 


文字 终端 长 期 支持 非常 标准 化 的 控制 序列 。 它 经 常 被 用 来 增强 终端 输出 的 可 读 性 。 
例如 grep --colour 。 e > uv_tty t 抽象 (stream) 和 相 
关 的 处 理 ANSI escape codes 的 函数 。 这 也 就 是 说 ，libuv 同 样 在 Windows 上 实现 了 
对 等 的 ANSI codes， 并 且 提 供 了 获取 终端 信息 的 函数 。 


首先 要 做 的 是 ， 使 用 读 一 写 文件 描述 符 来 初始 化 uv_tty_t 。 如 下 : 


Ant UM Ev Zmn1ttuv Loop Er, uv u yE uv Te fd nt readablei 


设置 readable 为 true， 意 味 着 你 打算 使 用 uv_read_start 从 stream 从 中 读 取 数 
Ap, 

最 好 还 要 使 用 uu Cru set mode 来 设置 其 为 正常 模式 。 也 就 是 运行 大 多 数 的 TTY 
格式 ， 流 控制 和 其 他 的 设置 。 其 他 的 模式 还 有 这 些 。 


记得 当 你 的 程序 退出 后 ， 要 使 用 uv_tty_reset_mode 恢复 终端 的 状态 。 这 才 是 礼 
貌 的 做 法 。 Te 礼 狐 的 地 方 是 关心 重 定向 。 如 果 使 用 者 将 你 的 命令 的 输出 重 
定向 到 文件 ， 控 制 序列 不 应 该 被 重 写 ， 因 为 这 会 阻碍 可 读 性 和 grep。 为 了 保证 文件 
描述 符 确实 是 TTY， 可 以 使 用 uv_guess_handle 函数， 比较 返回 值 是 否 

为 UV_TTY 。 


下 面 是 一 个 把 自 字 打印 到 红色 背景 上 的 例子 。 





tty/main.c 


#include 
#include 
#include 
#include 


uv_loop_ 


LIVE E yak: 
imt main 
loop 


uv_t 
uv_t 


be 


} 


UV_W 
uv_b 
buf. 


<stdio.h> 
<string.h> 
<unistd.h> 
<uv . h> 


t *loop; 
tty; 


O 
= uv_default_loop(); 


ty_init(loop, &tty, 1, 0); 
ty_set mode(&tty, UV_TTY_MODE_ NORMAL); 


uv Ouess handle(1) == UV_TTY) í 

UV _write t req; 

uv_buf_t buf; 

buf base = "\033[41;37m"; 

buf.len = strlen(buf.base); 

uv_write(&req, (uv stream t*) &tty, &buf, 1, NULL); 


rite t req; 
uf_t buf; 
base = "Hello TTYNn"; 


buf.len = strlen(buf.base); 


uv_w 
uv_t 
retu 


最 后 要 说 的 是 uv_tty_get_winsize() 


rite(&req, (uv stream t*) &tty, &buf, 1, NULL); 
ty_reset_ mode( ); 
rn uv_run(loop, UV_RUN_DEFAULT); 


它 能 获取 到 终端 的 宽 和 长 ， 当 成 功 获取 


后 返回 0。 下 面 这 个 小 程序 实现 了 一 个 动画 的 效果 。 


tty-gravity/main.c 


#include <stdio.h> 
#include <string.h> 
#include <unistd.h> 
#include <uv.h> 


uv Loop CC Sloop: 

ME EE ty; 

uv_timer_t tick; 

uv_write_t write _ reg: 

int width, height; 

int pos = 0; 

char *message = " Hello TTY "; 


void update(uv_timer_t *req) { 
char data[500]; 


UV buf t buf, 

buf base = data; 

buf.len = sprintf(data, "N033[2JN033[HN033[%dBN033[%l1uCN033[42, 
pos, 
(unsigned long) (width-strlen(message). 
message); 

uv_write(&write req, (uv_stream t*) &tty, &buf, 1, NULL); 


pos++; 

if (pos > height) í 
uv_tty_reset_mode(); 
uv_timer_stop(&tick); 





int main() í 
loop = uv_default loop(); 


uv_tty_init(loop, &tty, 1, 06); 
uv_tty_set_mode(&tty, 0); 


if (uv_tty_get_winsize(&tty, &width, &height)) í 
fprintf(stderr, "Could not get TTY information\n"); 
uv_tty_reset_mode(); 
return 1; 





} 


fprintf(stderr, "Width %d, height %d\n", width, height); 
uv_timer_init(loop, &tick); 

uv_timer_start(&tick, update, 200, 200); 

return uv_run(loop, UV_RUN_DEFAULT); 





escape codes 的 对 应 表 如 下 : 


= 
oh 


码 意义 

2J Clear part of the screen, 2 is entire screen 

H Moves cursor to certain position, default top-left 

S Moves cursor down by n lines 

S Moves cursor right by n columns 

Se Obeys string of display settings, in this case green background (40+2), 


white text (30+7) 


正如 你 所 见 ， 它 能 输出 酷 炫 的 效果 ， 你 甚至 可 以 发 挥 想象 ， 用 它 来 制作 电子 游戏 。 
更 有 趣 的 输出 ， 可 以 使 


用 http://ww.gnu.org/software/ncurses/ncurses.html >° 


About 


Nikhil Marathe 在 茶 一 个 下 午 (June 16, 2012) 开 始 写 这 本 书 。 当 他 在 写 node-taglib 的 
时 候 苦于 没有 好 的 libuv 文 档 。 虽 然 已 经 有 了 官方 文档 ， 但 是 没有 好 理解 的 教程 。 本 
书 正 是 应 需求 而 生 ， 并 且 努 力 变 得 准确 。 也 就 是 说 ， 本 书 中 可 能 会 有 错误 。 所 以 鼓 
励 大 家 Pull requests。 你 当然 可 以 直接 给 他 发 email， 告 诉 他 错误 。 


Nikhil 从 Marc Lehmann 的 关于 libev 的 手册 中 讲解 libev 和 libuv 的 不 同 点 的 部 分 ， 获 取 
了 不 少 的 灵感 。 


本 书 的 中 文 翻 译 者 为 : Iuohaha，byronhe，Ilittleneko。 同 样 欢迎 您 的 Pull requests 
来 改进 本 书 的 翻译 工作 。 
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